5 ms·
Speaking from experience of a) working in a team and b) maintaining legacy code: Your code, no matter how good, will not instantly make sense to someone else.
by ErrantX 13y ago
Speaking from experience of a) working in a team and b) maintaining legacy code: Your code, no matter how good, will not instantly make sense to someone else.
Comments are essential. Writing good comments is as skilled a task as writing the code.
(as an aside; the most important comment is WHO. Because knowing who wrote/modified a block of code is ridiculously useful for all sorts of obvious reasons)
- _ZeD_ 13y agosvn / hg / git ... blame ? :D
- Roboprog 13y agoEven CVS has an annotate / blame / praise command as well, as do, for example, commercial systems like Clearcase and MKS source integrity.
- spellboots 13y agoIf you have to write who wrote a piece of code in a comment, you must not be using a decent version control system with a blame command. Which is a problem you should probably fix way before talking about comment styles.
- ErrantX 13y agoUh, that takes much longer. Blame is useful in more elaborate context but... comments are instant :) And that is important.
- jack9 13y ago> Blame is useful in more elaborate context but... comments are instant Blame is instant too, if you have a good and modern IDE. Can't always be relied upon, but once such a beast exists, just assume it's being used. Writing erlang? Sorry, inline comments. Writing JS/PHP? Leave it in git.
- vonmoltke 13y agoFair point, but I have two counterpoints: 1) Changing version control systems may be an unwinnable corporate political battle, while changing comment style may just be a team decision. 2) Not everyone who may need to understand or modify your code may have access to your repositories. I worked on a program where partner companies were provided source snapshots for developing their own algorithms but were not allowed access to our repositories.
- dragonwriter 13y ago> Because knowing who wrote/modified a block of code is ridiculously useful for all sorts of obvious reasons IME, the only use it usually has on its own is knowing which people that are no longer on the team to blame to blame for the poor state of the code (both the operational parts, and the absence of useful code comments on the intent or rationale for the current code structure.) WHO is not the most important comment (though its probably the most universally necessary part of a comment -- a need for a who comment always implies the need for some other comment, and most other comments should include a who.)
- ErrantX 13y agoI'm coming from a team whose policy is to create a PHP docblock for everything. This is actually dead useful because at a glance you see who wrote the code, exactly what you can pass into the function and what it will spit back out.
- dmgd 13y agoWhat are those "obvious" reasons? The only reason I've ever had for knowing who wrote code is if the code+comments+tests do not adequately explain what's going on and I need to know. On most of those occasions the person who wrote the original code had already left the organisation.