I am working with an in-house “rapid development team.” They have rigorous intake, story and task break down, scheduling of sprints, QA, definition of done, integration test coverage, E2E and min 90% unit test coverage etc. etc.
They have a strict policy of “no code comments, self documenting code only.” They will go in and remove comments that my DevOps team puts in there, because it screws up that policy.
Luckily, we adopted the policy of having local branches with these comments in place. Once they move beyond the project, we’re putting them in.
They do have a point though. When we’ve gone through phases where the industry focuses on commenting code and other documentation, most of it is useless.
Code comments should have a reason, and are no substitute for readable code.
However you’re also right though that people jump onto “all or nothing”. I recently did a code
Review that I held up for comments. In this case, they were doing something very atypical to get around a limitation so it was a clear case of comments needed. The next person through will say “what is this shit?” And “fix” it, without knowing there was a good reason
Yeah “why” comments are absolutely fine, “what” comments are useless at best and can be harmful at worst.
I feel like this constant flood of “write comments” posts are from CS students who are told to comment everything by their lecturers. Descriptive variable and function names help explain the “what” of code pretty well most of the time.
Sure with some old languages like C89 where you are limited in your variable name length you probably do need comments to explain wtf is going on, but most code bases aren’t as constrained.
I have this argument with other devs all the time.
Hey, you know this 200 line nested if statement that suddenly returns in the middle of the condition is “7”? Yeah, that needs a refactor or at least a fucking comment.
I get a pull request that adds a log line that reads something like “special case 7 triggered.”.
Having no comments doesn’t force code to be self-documenting. I understand the cult of code extremist, but No-Commenters are just WEAK and PATHETIC wannabes trying to immitate the true, functional extremists, such as the 16-Space-Tabbers
That’s silly. I’ve never seen comments even as a way to explain what your code is doing (the code often does do that anyway). It’s important to say WHY you’re doing it the way you are.
That way anyone else who comes in there can have the same context you did when you implemented it, which imo is where most bugs occur. People don’t realize what assumptions you made when it was first written, and then make their own (which can easily clash).
for i in array_sometimes_we_get_ints_from_upstream_functions_and_need_to_convert_them_to_floats_or_downstream_functions_throw_exceptions:
out_array.append(float(i)
I just love it when people who have no understanding of the purposes, objectives and applicability of various parts of a famous software development process and just follow it in a blind fashion-following way.
And by “love it” I mean “get frustrated to no end even though by now I should know better”.
I am working with an in-house “rapid development team.” They have rigorous intake, story and task break down, scheduling of sprints, QA, definition of done, integration test coverage, E2E and min 90% unit test coverage etc. etc.
They have a strict policy of “no code comments, self documenting code only.” They will go in and remove comments that my DevOps team puts in there, because it screws up that policy.
Luckily, we adopted the policy of having local branches with these comments in place. Once they move beyond the project, we’re putting them in.
The vitriol the “Clean Code” cult has against comments is unbelievable…
too many lines!!!
They do have a point though. When we’ve gone through phases where the industry focuses on commenting code and other documentation, most of it is useless.
Code comments should have a reason, and are no substitute for readable code.
However you’re also right though that people jump onto “all or nothing”. I recently did a code Review that I held up for comments. In this case, they were doing something very atypical to get around a limitation so it was a clear case of comments needed. The next person through will say “what is this shit?” And “fix” it, without knowing there was a good reason
Yeah “why” comments are absolutely fine, “what” comments are useless at best and can be harmful at worst.
I feel like this constant flood of “write comments” posts are from CS students who are told to comment everything by their lecturers. Descriptive variable and function names help explain the “what” of code pretty well most of the time.
Sure with some old languages like C89 where you are limited in your variable name length you probably do need comments to explain wtf is going on, but most code bases aren’t as constrained.
I have this argument with other devs all the time.
Hey, you know this 200 line nested if statement that suddenly returns in the middle of the condition is “7”? Yeah, that needs a refactor or at least a fucking comment.
I get a pull request that adds a log line that reads something like “special case 7 triggered.”.
Plot twist: it was a 7 Boom game.
Having no comments doesn’t force code to be self-documenting. I understand the cult of code extremist, but No-Commenters are just WEAK and PATHETIC wannabes trying to immitate the true, functional extremists, such as the 16-Space-Tabbers
That’s silly. I’ve never seen comments even as a way to explain what your code is doing (the code often does do that anyway). It’s important to say WHY you’re doing it the way you are.
That way anyone else who comes in there can have the same context you did when you implemented it, which imo is where most bugs occur. People don’t realize what assumptions you made when it was first written, and then make their own (which can easily clash).
for i in array_sometimes_we_get_ints_from_upstream_functions_and_need_to_convert_them_to_floats_or_downstream_functions_throw_exceptions: out_array.append(float(i)
I like you.
What’s fun is that this is C#, so no limit to the length of function names.
I just love it when people who have no understanding of the purposes, objectives and applicability of various parts of a famous software development process and just follow it in a blind fashion-following way.
And by “love it” I mean “get frustrated to no end even though by now I should know better”.
What sort of dev anarchy is this