The value of comments in code
#129 Henry, Tuesday, 08 May 2012 3:03 PM (Category: Programming)
(Tags: comment programming)

Last week at work, we had to review old code to see if it was useful and needed to be rewritten. We had to read through old C files and try and work out what they were. Luckily, many of them had copious comments at the beginning of each file, describing what they were for, what system they were part of, what they did, who wrote them and who authorised them. This was useful because many of these programs were written before 1993, and everyone who had ever worked on them is long gone. Thanks to sensible comments, we were able to understand what nearly everything was. It gave me a better appreciation for the value of comments.

Much of the documentation and change history had been stored originally in SCCS and then RCS and then CVS, but all of these have long gone too. We now use Subversion, and are thinking about git. Every time we change our revision control system, we lose knowledge. Comments embedded in the code are invaluable. I don't think everything needs to be in the text, but relevant details about what and who and why and when should be there. At the start of the file. I have done this with my code, mostly, but from now on I will do it assiduously.