|
Release Engineering
Being a team composed by developers from every corner of the world it is not always easy to create software that looks the same in its every part. Especially because each of us has own habits and weaknesses while coding. Yet, this should not mean that it is OK leaving the application looking like a Christmas tree.
The way we code should be standardized. It is not any nice opening a file and finding in it an alien, X-FILES like code where the only way to navigate is GREP or CTRL+F. That is why it is necessary to write the code thinking primarily on how others will understand it, and simplify the code, adding more comments to it so there would be fewer jungles between the lines.
PHP Code standards
No, I am not going to push anyone away from own programming practices, but for as long as they are clear to most other programmers.
I recommend make code clear without many exaggerations. Remember this good old quote - "only because we *can* doesn't mean we *should*, unless we *need*".
Below I will list a few rules for what everyone appreciates when reading someone else's (or team-made) programs.
Style
Style is a personal thing, but unfortunately, to let the rest of the team's life easier, it is better to use a standard one, which might not always be your preferred.
PHP usually keeps a C-like style. And, it is what we will set as the basic standard for ZoomStats. I just came across a nice document regarding this style. Of course, you don't have to religiously follow it in its exact form. Just let me mention you the most important parts:
- Indent (always) your code with one tab per block level (have your editor set to whatever number of spaces an indent should represent but save as INDENTS, not spaces)
- For blocks, use K&R (Kernighan & Ritchie) style. Those who "C" will know what it means, others look at it here.
- Keep at least ONE line between logical sets (controls), TWO or THREE before and after a large block and FOUR between functions, methods (objects, in other words).
- Do not put more than one instruction on the same line. E.g:
// this is not good
$foo = 'baz; $bar=baz;
// this is OK
$foo = $bar = 'baz;
- Keep at least ONE line between logical sets (controls), TWO or THREE before and after a large block and FOUR between functions, methods (objects, in other words).
- Avoid UpperCase file, function, variable and array element names. Use humanly readable and short names. Separating the words by using under_score (_) is better than UpperCase (even if sometimes it could look cooler, it is still a "wrong", or rather "inconvenient" style).
This is very useful for many developers to intuitively guess variable names within application. Exceptions should only be few and very special names (in only case insensitive situations). SQL can be whatever case, as long the names are standard, but that is another story.
- Variable names must be meaningful. One letter variable names must be avoided, except for places where the variable has no real meaning or a trivial meaning (e.g.
for ($i=0; $i<100; $i++) ...). Read also above for more styling on variables.
Commenting your code
This is something very important. To be honest, I always hated doing it, but commenting is actually a time saver rather then time consumer. Who programmed for at least one year will know how hard it is to understand your old code. Human's brain cannot remember everything done in past, so even your own code has to be transcribed if wrote relatively long time ago. Obviously, situation gets worth when more developers are supposed to read your code as well.
So, please, always follow these "10 commandments":
- Comment lightly each block of your code. e.g:
// get name if not set
if(!isset($name)) {
$name = get_name();
}
- Always use (// ) (unless it is an object, see below) as it would be easier to comment more blocks at the same time using (/*) and (*/).
- (// ) comments are preferably to be on top when within statements.
- Comment the objects (classes, methods, functions, DB tables, SQL commands etc). Look at the code to see the samples (simply cut&paste, then modify)
- Make things look nice - align your comments. The best way for it is, again, by copying an existing comment block modifying it.
- While commenting large blocks, please describe them well - these, eventually, might go to the official documentation.
- Object authors. Author of a block such as function, method or even a class is the person that first made it and/or who latter edited it (not the one who just fixed a tiny bug - be proportional and generous.)
- In object comments, authors should be represented one per line with their name and email. Doesn't matter what name and email you choose, as long as it is consistent within the rest of the application. I advise you to spam-protect your email addresses like "maxim at php dot net". The emails found within the code will help us debugging ZoomStats as it would facilitate end-users modifying your code to send you the changes they make.
- File Maintainers. These are the list of the people that MAINLY participated in creation and are the ones mainly responsible and familiar within the file. For instance, if I was to fix a few major bugs within Sybase section of ZoomStats I would, maybe, add my name to the function that I modified, but I would not add myself to the maintainers of that file since about Sybase I only know it is some database's name.
- CVS commits. On each file change make a sense-making commit message. If, while working on the same file, you are doing more than one task - commit them separately with separate messages. This seriously helps tracking down the project development history. Also, if the change made is quite of a big importance, add it to the "Development History" tracker.
Examples
If statements
<?php
// This is for the simple idea on how
// brackets should be used
if($foo == $bar) {
$result = $this->class_method($foo);
}
else {
// We'll try another method
$result = $this->another_method($foo);
}
?>
Ternary operator
<?php
// This is for the simple idea on how
// ternary operators should look
$result = ($foo == $bar)? $this->class_method($foo) : $this->another_method($foo);
?>
Functions
<?php
/* Method: foo
+----------------------------------------------------------------------+
Scope: Public
Authors: Maxim Maletsky (maxim at php dot net)
Description: Just a simple function to show as an axample
+----------------------------------------------------------------------+
*/
function foo($foo, $bar='') {
if($foo == $bar) {
Return $this->class_method($foo);
}
else {
// We'll try another method
Return $this->another_method($foo);
}
}
?>
Conclusions:
- Be as clear as possible commenting your code - it is both our internal and external documentations - we do it for ourselves and for the rest of the world.
- Do not write weirdly looking code, not everyone can guess it from the first time, and, not guessing from the second time is even more frustrating.
- Don't get innovative in your coding style - write your new code following the style of the already written one. It only simplifies our lives. However, if you think you have better idea regarding something - discuss it, then we can call it an innovation.
|
