Of Code and Comments
-
We had lots of discussion about this at work too, about how extensively code should be commented, and if at all. First there is a difference between commenting and documenting code. The latter you probably need to do anyway, at least for public APIs. Besides that, imho some visual indicator on top of each function / class etc makes it easier to navigate through code. So a short block on top of each function can act as kind of a separator (like headlines in normal texts), that allows to quickly see where a function starts. So (meanwhile) I add at least a single line with dashes on top of each function, and find that quite useful. As for comments, I agree with those people, who say code should be written in a way that comments are not necessary. Means: Use names that say what it is about rather than comments, split complicated constructs into multiple steps, even if it appears less "cool" (functional programming!) etc. However, there are cases, where comments are a good idea. Not just to explain some parts of the code that are hard to understand, but also to indicate that something might look like a bug or a wired construct, but is actually intended. Like this JS:
const a = parseInt(someString, 10);
if (!(a > 0))...One might think "Wtf? Why not
if (a <= 0)...?", and forget, that the former also takes care ofNaN. So my personal guideline: - Write code that doesn't need comments. - Comment to avoid misunderstandings. - Document your code.Thanks for the point for use in js to avoid NAN. I did not know that.
-
Evening folks, Not sure which board this question/rant belongs so I am just going to put it on here. I would love to know how people generally feel about comments in code as a means to describe what the code does. In my workplace that I only started at about 2 months ago, I have already had about half a dozen discussions about why I think code comments are a) largely a waste of time b) distraction from writing the actual code c) give license to a developer to be sloppy with their code. Kevlin Henney's talk on this subject is pretty much along the same lines but there must be some bigger picture that I must be missing that my colleagues in office know that they are forcing me write comments in code. I have been developing software for about 11 years professionally and 15 years if you include the pizza and soda filled days of academia and I have transitioned from code commenter to just writing clean enough code that tells the reader what it does (thanks to Uncle Bob!!) so I find it incredibly backward having to go back to writing comments just to save my job. I do understand in some cases comments might be necessary where the code intrinsically is complex and cannot be refactored any more but putting documenting comments on every class, function and property just for the sake of it seems ridiculous. I also understand publicly consumed APIs need to have documentation so client developers can build apps on top of them but anything beyond these 2 use cases, is stupid IMHO. Thoughts, outrages, feelings? Cheers IEC
I came from a background of profusely commenting code to a job(last year) where comments are explicitly discouraged and code reviews will be failed if there is a comment. There are a few cases where comments are allowed - for very complex issues - but other than that comments are not allowed. I struggled at first but it has actually made me a better developer as I now have to read and understand what others have don in code rather than just read a comment and think I know what a method or stored procedure does. So I am a convert to sparsely commented code as I tend to agree with the principle that writing comments means that you have to keep the comments up-to-date and it has encouraged me to both write better code and understand other peoples' code.
“That which can be asserted without evidence, can be dismissed without evidence.”
― Christopher Hitchens
-
I came from a background of profusely commenting code to a job(last year) where comments are explicitly discouraged and code reviews will be failed if there is a comment. There are a few cases where comments are allowed - for very complex issues - but other than that comments are not allowed. I struggled at first but it has actually made me a better developer as I now have to read and understand what others have don in code rather than just read a comment and think I know what a method or stored procedure does. So I am a convert to sparsely commented code as I tend to agree with the principle that writing comments means that you have to keep the comments up-to-date and it has encouraged me to both write better code and understand other peoples' code.
“That which can be asserted without evidence, can be dismissed without evidence.”
― Christopher Hitchens
GuyThiebaut wrote:
comments are explicitly discouraged and code reviews will be failed if there is a comment.
Ah, so you work in Hell. Could you put in a good word with your CEO? I might end up there so...
* CALL APOGEE, SAY AARDWOLF * GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- ++>+++ y+++* Weapons extension: ma- k++ F+2 X * Never pay more than 20 bucks for a computer game. * I'm a puny punmaker.
-
GuyThiebaut wrote:
comments are explicitly discouraged and code reviews will be failed if there is a comment.
Ah, so you work in Hell. Could you put in a good word with your CEO? I might end up there so...
* CALL APOGEE, SAY AARDWOLF * GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- ++>+++ y+++* Weapons extension: ma- k++ F+2 X * Never pay more than 20 bucks for a computer game. * I'm a puny punmaker.
den2k88 wrote:
Ah, so you work in Hell.
That's what I thought to begin with. However the advantage of no comments is that that the code needs to be really tight and well written and the code reviews help that too - you cannot rely on the comments to make sense of the code so it needs to be well coded. It has also helped me read and understand other people's code much better. I am a convert.
“That which can be asserted without evidence, can be dismissed without evidence.”
― Christopher Hitchens
-
I've been writing software for almost 40 years, and I'll take your bait. ;) As is the case with almost every engineering issue, there is a fine line between appropriately commenting code and commenting just to fill a space. To that end, I think you are partially correct, but I think we differ in three key respects, unless I misunderstood you. - Every function or method should be prefaced with a short explanation of the algorithm that it implements or the task that it performs. Obviously, if the function is part of the public interface, this comment should take the form of an XML comment, which need not be repeated as a regular comment. You can also make a good case for attaching XML comments to every method. Indeed, I usually follow this practice in my own work, and I've seen it often in the work of others. - Every class must begin with a short explanatory comment about its purpose. As is the case with methods, this can take the form of XML commenting. - Every module must contain a change log, and you must be fastidious about adding a note, brief though it may be, every time you change it. With respect to the third point, some would argue that this is the purpose of check-in comments, but my experience has been that these are almost invariably insufficient to properly document what changed, and why a file was included in a given changeset. I have wasted many valuable hours, usually aided by side by side changeset comparisons, to obtain such knowledge, which would be ridiculously easy to put into a change log. In my view, the changeset log is just not sufficiently granular to be your whole change history. Finally, in the first point, I mentioned attaching XML comments to all methods. The benefits of doing so are twofold. 1 Since IntelliSense picks up local XML comments, it's easier to consume provate methods in other parts of the same project. 2 If you decide later to make a class or method public, the XML comments are already there, so the only required change is to the access modifier. While I agree with you that commenting can be used to compensate for sloppy code, there are some things that just cannot be documented by the code alone.
David A. Gray Delivering Solutions for the Ages, One Problem at a Time Interpreting the Fundamental Principle of Tabular Reporting
Personally, I try to use *doc* style (Javadoc, Doxygen, Pydoc). For C/C++ only in the header files. However, I only comment the stuff I think is helpful to maintain the code. Most developers forget to modify existing code comments, so there's no need to be pedantic and comment about what is clearly gleaned from the source:java:.
-
That's exactly what I have been pondering! :) Probably in time I can show them with evidence that if you write clean enough code, comments become more or less useless. I guess a lot of it comes from their past experience working with the current version of the product which is written in classic ASP (not even Web Forms) and its been written so badly that comments became a necessity and a bit of license to continue writing sloppy code. They have hired me to help not only rearchitect the product to bring it into 21st century but also establish other practices like TDD, Scrum, CI/CD etc which they haven't really done in the past so its my job to shine a light on what needs to be done but they still seem to carry the paranoia from the past which is making them edgy about me not putting any comments in the code. Perhaps I should stop pushing so hard initially and observe! Thanks! :) What do you think about code comments though?
to one person a parameter in a function (e), means event, to another is meaningless. Hench why i prefer function(event) over a comment saying e is event. I have not been shown that writing like every single bit for variable names is needed in the last decade. oh its 10 charters vs 1, so much ram and memory, and file size. a decent compiler will parse it. I am not long names for the compiler, I am writing for some human.