1532
Comment Your Code People
(suppo.fi)
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
this post was submitted on 02 Oct 2023
1532 points (98.4% liked)
Programmer Humor
32171 readers
728 users here now
Post funny things about programming here! (Or just rant about your favourite programming language.)
Rules:
- Posts must be relevant to programming, programmers, or computer science.
- No NSFW content.
- Jokes must be in good taste. No hate speech, bigotry, etc.
founded 5 years ago
MODERATORS
Code is the documentation. Any other form of documentation requires additional maintenance and becomes obsolete quickly.
all functions should at least have doc comments on them
No. Just give the function a good descriptive name with good descriptive parameters. Keep the function simple too. If you can’t, try to refactor and see if that helps.
If you are still unable to express yourself via code, then you should use comments to guide the reader.
What about exceptions raised within the function? Will you also put them in the descriptive function name? ;)
You can find them by reading the code. It’s not difficult if they’re placed at proper locations.
But a major point of a function is that you not have to read its implementation details.
According to who? If I have access to the source code, which I often do, I’d rather just read the code. Chances are that if documentation exists, it’s no longer up to date.
Modularity. Part of it is defining a proper Interface for using the hidden complexity.
Exceptions are only one example. Functions can have behavior, inner states, prior calling requirements etc.. you cannot read from its mere prototype.
Do you really want everyone to read the inner code to learn that?
This risk also applies to descriptive function names. They can be poor, wrong or outdated, too.