SMF 2.0.19 has been released! Please update. Read more.

Main Menu

Coding Guidelines...

Started by [Unknown], March 13, 2004, 05:03:59 PM

Previous topic - Next topic


I've noticed sometimes people don't exactly realize these, or forget them and so I'd like people to post and read these, please.

- always free MySQL result resources. (as well as other resources!)
- keep correct documentation at the tops of files.
- keep the documentation at the tops of files limited to a width of 80 characters.
- no duplication of comments if at all possible. (so they can be searched for uniquely.)
- as always, descriptive variable names are much better than "$egYtesIopnfer" type ones. (except when using counters, $i, etc.)
- code in script.js should only be GLOBAL for almost ALL themes, not for just the default theme. (unlike style.css.)
- don't be afraid to use blank lines between logical "sections" of code, but don't use too many because it makes it too spaced out :P.
- always have a newline before an opening or closing brace. ({/})
- in queries or code, always have spaces before and after operators.
- always put an alt attribute on all image elements, even if the alt is empty.
- do not use title for the purpose of alt, only use it when a title is needed. (like for icons.)
- always close input, img, hr, and other elements that can't contain anything. (<name />)
- do not use multiple class names in the class attribute, even though this is in the spec; instead use extra divs or spans.
- always use style="check" on input[type="radio"] and input[type="checkbox"].
- unless under special circumstances, outside links should open in _blank, all others with no target.
- no queries or "advanced" code should ever be used in the default templates.
- avoid globals whenever possible, try to keep all variables local.
- any changes to the "main" templates (index, BoardIndex, Display, MessageIndex) should not be required for continued operation.
- in queries, always capitalize commands: SELECT, INSERT, REPLACE, UPDATE, DELETE, etc. should be all uppercase.
- in queries, always capitalize WHERE, AND, OR, LIMIT, FROM, JOIN, AS, ON, etc.
- always break after ANDs in queries, don't break after OR unless for readability.
- avoid field names that are also keywords in MySQL.
- do not use any features of MySQL not available in MySQL 3.23.4 and lower.
- optimize all queries for MySQL 4, although they as above should work in lower.
- do not use functions that do not exist in PHP 4.1.0 or lower (and don't use functions that have been removed later either!) unless you define them for those versions.
- keep all id attributes unique, and try to keep id and name the same if both are specified.
- either use underscores or internal capitalization for variable names.
- don't use abbreviations in $context index names.
- use session checks for any and all actions that *do* something.
- start each comment line with a capital letter, and use proper grammar. (periods at the end and all!)
- use LIMIT for queries whenever possible.
- use // style comments over /* */ comments when possible.
- avoid requiring a specific group to do things; instead, use permissions.
- LEFT JOINs are slower than regular JOINs (or commas) so they should be avoided if possible.
- it's not messages as m, but messages AS m, because AS is a MySQL keyword.
- we don't need functionality in there that most people won't use.
- when doing a JOIN, the joined table's column(s) come first in the ON clause.
- do not use heredoc or print(). use echo with single quotes if the text is long with few variables.
- when outputting something using echo, use commas to input a variable (echo 'foo', $bar, 'foobar';



Well - it's not *always* followed but all sub tables/columns/rows should always be indented by a tab, and should always line up appropriatly (so you know which table a row is nested inside etc)
I'm only a half geek really...


Well, that's more discretional imho.  As long as the html is logically laid out, it doesn't have to be indented once per element neccessarily.



s/MySQL 3.23.4/MySQL 3.23.6/ for 1.1.

Keys for the context arrays and sub arrays should always be lowercase and separated by underscores.



I just wanted to make a note here since Grudge mentioned possibly turning this isn't a page somewhere on the site for us.
It would be great if under some of the points an explanation was given. Like "always free mysql resources (and other resources as well)" - what is the technical reason behind that, and what are those 'other' resources? I think it would be a great way for people to learn and expand their comprehesion and grasp of the code/language/etc.
If I know the way home and am walking along it drunkenly, is it any less the right way because I am staggering from side to side? : Leo Tolstoy
Everything I know I learned from Calvin and Hobbes.
And patience is about the most useful thing you could ever have.  That and backups. : [Unknown]
If I choose to send thee, Tuor son of Huor, then believe not that thy one sword is not worth the sending. : Ulmo, Lord of the Waters - Unfinished Tales, by J.R.R. Tolkien


Uh, you see, that's one of the reason the php documentation existed... Memory, especially for scripts, are limited, as are database connections, so if you don't free them they may accumulate and kill the script prematurely before the script ends (when everything should be freed automatically).

An example of other resources is file resources.  While there's not much of that in SMF, there are php philosophies that relies heavily on them for, say, data storage or simply as mutex.