|
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'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
|
|
|
|
|
Yeah I was referring to the XML comments and specifically in C# and I appreciate your point that not everything can be communicated by the code sufficiently clearly for e.g. a complex algorithm implementation that might require some additional prose to describe the whats, the whys and the hows. Perfectly acceptable.
However, I don't agree with putting even XML comments everywhere even when the code is self-evident. If I as a developer don't write clean enough code that reveals its intentions and purposes then how can I be relied upon to write clear concise comments? At best/worst I might be lying about the code which probably will become clear in code reviews but code reviews are about the code, not comments. Code executes, comments don't. If I am going to spend effort anyway, I'd rather use it to refactor code, not comments. Not to mention maintaining code itself is a major task add to that the burden of maintaining the comments and the whole thing becomes a real drag on programmer productivity. I much rather spend that time on refactoring and testing the code to make it as clear and provable as possible.
Plus, compiler provides little to no support for comments (apart from cosmetic colour coding) and any time I change a method signature or the purpose, comments don't auto update because they can't read my mind! Now, office politics perhaps may be a reason why someone might get forced to write comments despite their better judgement, which I think might be at play in my case.
On the change log, I believe check-in comments are the place to put your reasoning to have changed any code. This way I can look at the comments in source control and if I feel like I can just do a diff to see what changed and whether or not it correlates to the comment. Ultimately, its about the developer discipline and I much rather use it to write meaningful and clean code, test cases and check-in comments rather than bunging everything in the source code file that contains everything but meaningful code. Its like my grandma used to say, "Everything in its place and a place for everything!".
Thanks for your input anyway. Appreciated! 
|
|
|
|
|
Well, then, your check-in comments must be books. Most of the ones I've seen, and even written, are no more than a paragraph.
Furthermore, if I put everything in the check-in comments, than I have to keep a Team Explorer window open to see them. If it's related directly to Module A, then it belongs in Module A.
David A. Gray
Delivering Solutions for the Ages, One Problem at a Time
Interpreting the Fundamental Principle of Tabular Reporting
|
|
|
|
|
You don't actually have to document every single line of code that you change (unless you were writing software for safety critical systems), if you follow "Check-in early, Check-in Often" then you're only describing the change as succinctly as possible with each check-in as your changeset is likely to be relatively small. Things tend to get messy if you are into big shot releases where changes have been building up for weeks on end if not months, in that case of course you would lose the track of what has changed and why.
The worst I have seen so far in my experience is someone, and at times me too, had to put in 2-3 mini-bullet points to describe the change at a logical level. But change logs in source files is an old fashioned concept and I haven't really seen it in the places I have worked in so far so I am not going to worry about that as much. My main gripe is with source code comments.
|
|
|
|
|
IMO, old-fashioned != outdated.
As an example, last year, I had a changeset that included models, views, and controllers for two entities. A few weeks later, when I reviewed the code for another use story, I found myself scratching my head about why the view, which shouldn't have been affected by the changes to implement the last user story that touched these modules. I eventually figured out why it got in there, but I wasted a good deal of time on it that could have been put to better use working on another user story.
Histories were banned at the last two places that I worked. Instead, programmers were urged to enter dated comments adjacent to code changes. While this is nice, and I do that, you can't find them without searching the file for a date, and praying that everyone writes theirs in the same format. A history at the top of the source file is easy to maintain, and is discarded by the compiler, so has no effect on the generated machine code or byte code.
When I review source code that has a history, I can frequently confine my examination of a particular file to its history, because I can learn everything I need to know about it from the last entry or two. Working on a complex application that has many moving parts, changeset notes just aren't enough. Besides, they are not written until after the change is made and tested, when it's harder to remember why you changed each file in the set.
From time to time, I've brought some of my own code into a project, and when I've done so, the history stayed with it.
I wrote my first "real" program in 1978, and everything that I just said is the result of almost 40 years of hard won lessons, some learned when I stopped doing something that I thought was unnecessary, or had been superseded by some newer method that was allegedly better. I can't count the times that I've had to revert to my "old" way of doing things, because the "new" way was just too unproductive. Histories in source code belongs on that list.
David A. Gray
Delivering Solutions for the Ages, One Problem at a Time
Interpreting the Fundamental Principle of Tabular Reporting
|
|
|
|
|
To each their own, I guess! I prefer to put these kinds of comments while checking-in/pushing my work to the source control. I don't like the source file bloat irrespective of whether or not you can collapse such sections. With the use of labeling, tagging and linking the changeset with the user story right from within Visual Studio (at least) I personally don't feel there is any extra wastage of time if you need to know why something was changed.
Usually for these kinds of comments I am only describing the reason for change at a high level may be in the language of the acceptance criteria described in the backlog which keeps things nice and clear. For everything else, one can read the code.
|
|
|
|
|
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 | [Coffee]](https://codeproject.global.ssl.fastly.net/script/Forums/Images/coffee.gif) .
|
|
|
|
|
I am going to have side with David (@Enigmatic-Texan) on this one. If you rely on code documentation tools, such as SandCastle, the inclusion of XML comments on all public methods and properties is a must. Also, I also agree with your statement that if the code is complex and hard to decipher than comments walking someone through it is a must. Even I have written code that, when re-visited, elicits a  response. Comments for the sake of comments could be considered a waste of time. Heck, I usually don't comment my code until it's time to start building the documentation.
if (Object.DividedByZero == true) { Universe.Implode(); }
Meus ratio ex fortis machina. Simplicitatis de formae ac munus. -Foothill, 2016
|
|
|
|
|
Thank you for reinforcing my case with more evidence. I've been in exactly that place, and have been from time to time forced to augment the original comments to reflect things that should have been there in the first place, but weren't, leading to much head-scratching months, or even years, later.
David A. Gray
Delivering Solutions for the Ages, One Problem at a Time
Interpreting the Fundamental Principle of Tabular Reporting
|
|
|
|
|
I.explore.code wrote: 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
You can stop there; this happens in every industry.
You are new, and come in telling the people who have been working there that they are doing it wrong. Even if you are right, there's a good chance you'll loose.
Wait half a year, and walk the distance in their shoes for that time. Then, gradually, improve your own code and give it to a senior co-worker to validate.
Bastard Programmer from Hell 
If you can't read my code, try converting it here[^]
|
|
|
|
|
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?
|
|
|
|
|
I.explore.code wrote: What do you think about code comments though?
Mostly that there is no "perfect" approach
My personal code has few comments, mostly small sidenotes that are supposed to remind me whenever something might be different from my initial expectations.
At work, we do XML-documentation, mostly according to MS standard. It is verified during a build, and the build will fail if a public method is missing a documentation-tag for a parameter. There no single method is without documentation, and the source-code can be used to generate a MSDN-like overview of your classes and the (XML) comments. That in turn is very nice when going through a new codebase, trying to make sense of the code.
..as long as you don't include a useless header above an almost empty piece of code, I'm happy. (Try the C-Sharp IDE for a taste of that)
I.explore.code wrote: 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
They have maintained the code, cared for it, and it clearly worked for them in the past, and here you come with all these changes 
..does the rest of the team know of your mandate? Is the chief-architect actively supporting those changes? Can you explain how the new situation will be an improvement?
Bastard Programmer from Hell
If you can't read my code, try converting it here[^]
|
|
|
|
|
Eddy Vluggen wrote: They have maintained the code, cared for it, and it clearly worked for them in the past, and here you come with all these changes
..does the rest of the team know of your mandate? Is the chief-architect actively supporting those changes? Can you explain how the new situation will be an improvement?
Well, maintenance and care is precisely what's lacking in the current product which has been built in an adhoc way over the years in every which way by different types of developers. Its a maintenance nightmare by their own admission, so it hasn't "clearly worked" but "somehow worked" for them.
The team working on this rewrite is only 3-4 people (for now) me, another senior dev, a product manager and a lead dev who's the only person who's worked on the old product and knows a lot more of it, rest of us all are new hires. During my interview with the lead dev and the director it was made amply clear that they lack experience in Azure, Scrum, TDD and they are looking for someone with new ideas and who can "rock the boat". Having worked on rewrites before in similar environments where I wasn't just a developer who got handed down specs but was actively contributing to the architecture and design of the product (i.e. senior dev), I fit the bill. We discussed at length about various architecture and design options available to realise the product vision during the interview and again during my casual visits to their offices until I formally joined.
So I would say, the team was fairly aware of my mandate, but I guess they are not budging on the comments issue so my best strategy is write clean code and comment only where I must and then butt heads if that becomes an issue. Moving on is always an option if there is no clear resolution because I am not going to just accept it simply because the lead dev says so. If I didn't know any better myself, I would accept but I do know better.
|
|
|
|
|
I.explore.code wrote: Moving on is always an option if there is no clear resolution because I am not going to just accept it simply because the lead dev says so.
You don't want a war over comments. Or while we're there, coding guidelines
I.explore.code wrote: If I didn't know any better myself, I would accept but I do know better.
No problem - bring hotdogs on a slow day and explain the proposition - just remember that it has to add something tangible, it has to have some benefit. Simply being academic right will be seen as a timewaster. Albeit that may be forgiven, depending on the wurst
Bastard Programmer from Hell
If you can't read my code, try converting it here[^]
|
|
|
|
|
I understand code comments is probably a small issue compared to the larger goal that needs to be achieved here and there is probably no real resolution to this.
Opinions abound on both sides of the table, I personally feel writing code comments despite having written clear enough code, is a bit brainless exercise really. Everyone has a bit of ego and everyone wants to feel in control of something in their lives, lead devs/chief architects are more so, therefore in an effort to tacitly assure the lead dev that I am not here to take his job away from him or make him feel stupid, I am going to sprinkle comments where needed. Same goes for coding standards.
Eddy Vluggen wrote: No problem - bring hotdogs on a slow day and explain the proposition - just remember that it has to add something tangible, it has to have some benefit. Simply being academic right will be seen as a timewaster. Albeit that may be forgiven, depending on the wurst
Short of e-mailing them the links to dozens of blogs by well known people that agree with me on this, I don't think I can do anything else that can add tangibleness, especially after having had lengthy discussions in which I laid out my points as objectively as I could. I guess some lead devs have a real hard time coping with the possibility that their point of view could be wrong! No one likes to admit their fallibility!
|
|
|
|
|
I.explore.code wrote: I personally feel writing code comments despite having written clear enough code, is a bit brainless exercise really
To avoid discussions on what is "clear enough" we simply comment everything (public). What is clear to you now may not be so clear in five years.
..and it hardly costs much time to type it, if it is a brainless excercise
Bastard Programmer from Hell
If you can't read my code, try converting it here[^]
|
|
|
|
|
Not averse to writing comments where comments make sense, blanket bombing the source file with comments is just daft IMHO!
Plus, I don't think one can ever avoid discussions on clear enough code, they are called code reviews! Writing comments is no guarantee that it will still be clear in five years, a lot changes in our industry patterns, practices, styles, programming languages, architectures, people etc so there is no guarantee what made sense 5 years ago despite the comments, will still make sense 5 years on. I'd much rather refactor the code than refactor comments!
|
|
|
|
|
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.
|
|
|
|
|
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 of NaN.
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.
|
|
|
|
|
|
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.
|
|
|
|
|
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
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
