Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Why I refuse to give up code comments

ewanvalentine.io

Post reply on HN
Print view View original

11–16 of 16 posts

Re: Why I refuse to give up code comments

#11

Post by OtterCoder »

scerruti wrote: post #9
OtterCoder wrote: post #8

Earlier quoted context omitted.

I think you have a bit of a bias coming from Javaland. Java code is incredibly verbose for the sake of allowing the developer a thousand places to write self documenting code. It's a slog to write, but easier to read, by far. In functional languages, a single filter-map-fold can accomplish what might take half a dozen classes in Java. In those circumstances, a line or two of comments explaining the rough idea of what…

Yes, my son is currently writing a lot of functional code and complaining when I force him to do something in Java. It bothers me that we see the verbosity of Java as a detriment and then say we should add comments to functional languages. Don't get me wrong, I strongly believe in the appropriate functional approach where it's beneficial, but I strongly believe that it needs to be as self explanatory as Java code, ot…

> But given the choice between a developer who communicates clearly in code and knows it and one who either needs or believes he needs comments I'll choose the first.

This really just reads to me like you're selecting for hubris over humility, which is not likely to get good results over the long term. Give me a coder who doubts his code any day, over someone overconfident.

Re: Why I refuse to give up code comments

#12

Post by samy80 »

Good code should be readable and self explanatory. Comments should not focus on explaining the code, but rather present the overall logic. A good piece of code is one that doesn't need the reader to get into the implementation details. Commenting code is an art...

Re: Why I refuse to give up code comments

#13

Post by samy80 »

stephen wrote: post #7

Agreed with OP; my succinct version is: use comments for why not what . E.g. comments about "what" will be repetitive, out-of-date, etc. But comments about "why" we're doing something a particular way, especially if it's odd, are great sign posts to future maintainers.

Precisely

Re: Why I refuse to give up code comments

#14

Post by dictum »

I refuse to give up comments too. For personal projects, I prefer to keep comments outside the code as much as possible, in separate documentation files, so I can read more code vertically (no comment folding solution ever fit my needs).

From experience reading my own code and other people's code, it's never "self-documenting".

This trend is a combination of an attempt to nudge developers to take better care of the code so it's less dependent on comments (a good principle, but too optimistic), good old arrogance (this is a great team, no bad code ever gets written here), a fear of judgement (too often the comment will show what the person writing it understands of the code, including parts that are unclear to them).

The previous motivations can be reduced to this: some billion-dollar SV startup must be banning comments in their linter rules. And if some well-funded startup is doing that, everyone must do it too. It's the unwritten overriding law of software development.

Re: Why I refuse to give up code comments

#15

Post by INTPnerd »

philipwhiuk wrote: post #6
INTPnerd wrote: post #3

I mostly agree with you. I think the key is to always keep improving the code, don't expect or try to achieve perfection, and keep refining your concept of what makes for "improved" code. So if you come across a method name that does not clarify enough for you what it does, and there are no comments to help, you might start by getting your questions answered, and then add comments that help clarify things. If you sto…

> So if you come across a method name that does not clarify enough for you what it does, and there are no comments to help, you might start by getting your questions answered, and then add comments that help clarify things. And the logic for not renaming the method is what exactly?

I'm not saying you should not rename it instead. I'm just suggesting that there may be times when placing a helpful comment is easier than renaming it. So you might start by adding a comment, and then consider if you can rename the method to not need the comment. But you are right that if there is an immediately obvious way to rename the method to add clarity, you could just do that and be done.
Post reply on HN