This is a very simple idea about writing what goes on in your head inside source code file comments. So, my approach is that when writing code, it's not necessary to write comments about what the code does as long as you use suggestive variable names and methods for the objects you create. In other words, you can „let the code speak for itself“.

In languages such as Java and C#, methods have a typed return value. In PHP however, any method can return any type of value, such as null, boolean, object, array… And different coders use this capability in different ways. For example, you can design your methods to return false on error, rather than using exceptions. Or, you can make them return an array of values, which you then extract(): later. It's all good as long as it's consistent. But in order to make your code easier to understand by others (who may not be familiar with your conventions), it's a necessity to comment the methods with a simple description of what the method does, the parameters it can take and about the returned value.

But the practice I found extremely useful is to comment the thought processes occurring when writing code. I like to type this as a dialog, or a q&a. It may not make much sense to do this at first, but it's vital later when you try to remember why you made a specific design decision. This way, design involves an argument with yourself, done over time:

...
/**
 * "Why is method called foo()?"
 * "Because it returns bar"
 * "But why should it return bar? Shouldn't we create a new class and move it there..."
 * "Maybe, but let's let it like this for a while then see what happens"
 */
public function foo() {
  ...
}
...

This would also work for a number of programmers and it would look just like a chat:

...
/**
 * <Programmer1> Hi, ASL PLS
 * <Programmer2> U 1st
 */
...

No, not that kind of chat! Well, you get the idea – they could log the debate about design decisions with the help of comments, hoping it would be useful in the life cycle of the application.

POST#0059 2009-FEB-12

Help improve the Fusion Blog - express your opinion about the content on this page:   I like it   Can be improved

Commentary:

No comments so far. Why not add one?