Although documentation is great, too often I have seen it get out of date, especially the big block comments above the functions. It also becomes to understand a big block comment, especially if the comment is too detailed, since you have to keep jumping between parts of the code and parts of the comment.<p>I like shorter high level block comments and a lot more short comments that are directly next to the complicated parts of code it tries to explain. This way the block comments will stay up to date, and it is easier to update a short comment next to the specific lines of code. Since writing a short sentence about what you have just worked on is easier than adding to a large intimidating paragraph.<p>But the from my experiences, the beast practice is to write clean understandable code that does not need comments; updating code is mandatory to fix bugs but updating comments is an annoyance. Code reviews do marvels at reinforcing this, especially if the reviews are done through some tool that allows your coworkers to attach comments to specific lines of your code. This way the people can see specific problems and learn from each other. Also the social pressure of having your code definitely seen by others makes you write much cleaner code, as making the same mistakes over again will make you seem stupid.