3 ms·

So you're saying cant read existing code in order to understand it, or you just wont? Not arguing that self-documenting code is a good excuse for not documentin

by scient 8y ago

So you're saying cant read existing code in order to understand it, or you just wont? Not arguing that self-documenting code is a good excuse for not documenting anything, but if you have to write an essay to go with your code, maybe the code itself is not that great?

otras 8y ago
This is an odd false dilemma you’re presenting here. I don’t think that GP was claiming an essay along with the code is a good option or an indicator of great code, and that’s certainly not the only other option than self-documenting code.
mlthoughts2018 8y ago
That’s a false dichotomy though. There is a middle ground where you write concise, purposeful documentation regularly and try to automate and centralize it as much as possible. Occasionally, for very tricky algorithms or business logic, yes, you may need a few paragraphs in a comment to make it clear why something is happening. Especially if you take the perspective that you’re writing it for junior / unfamiliar readers, and not for people who could glean it from the code itself. But most of the time we’re just talking about concise function docstrings, a few lines about what a certain class is intended for. Most documentation won’t be essays. It’s also not about whether your code “needs” documentation or comments. The code should be clean and no more complex than required, always, and refactoring is to help do that over time. That has almost nothing to do with providing comments or documentation for future people who could be inexperienced, unfamiliar with that programming language, unfamiliar with that type of algorithm, coming to the source file many years after the last time it was edited, etc. The reasons to need documentation are many, and even if the code “is so good it doesn’t need comments” that usually does not matter at all to the person reading the code, and that person still does need comments. Thinking of comments as an indicator of inferior code is a dangerous code golf mentality that ignores the fact that you write comments _for people_, especially people coming to the code in a way that breaks all the assumptions the code author was thinking when they decided not to write comments.
IshKebab 8y ago
Some code is complex enough to need a proper explanation. Maybe you just haven't encountered any. I guess it would be rare in CRUD or web apps, but when you start getting into algorithms... Look at Ryu for example. Good luck understanding that without comments or documentation: https://github.com/ulfjack/ryu/blob/master/ryu/f2s.c https://github.com/ulfjack/ryu/blob/master/ryu/f2s.c
u801e 8y ago
No matter how well the code is written, without comments, understanding why it was written is going to be difficult to determine.

by scient 8y ago

otras 8y ago

This is an odd false dilemma you’re presenting here. I don’t think that GP was claiming an essay along with the code is a good option or an indicator of great code, and that’s certainly not the only other option than self-documenting code.

mlthoughts2018 8y ago

That’s a false dichotomy though. There is a middle ground where you write concise, purposeful documentation regularly and try to automate and centralize it as much as possible. Occasionally, for very tricky algorithms or business logic, yes, you may need a few paragraphs in a comment to make it clear why something is happening. Especially if you take the perspective that you’re writing it for junior / unfamiliar readers, and not for people who could glean it from the code itself. But most of the time we’re just talking about concise function docstrings, a few lines about what a certain class is intended for. Most documentation won’t be essays. It’s also not about whether your code “needs” documentation or comments. The code should be clean and no more complex than required, always, and refactoring is to help do that over time. That has almost nothing to do with providing comments or documentation for future people who could be inexperienced, unfamiliar with that programming language, unfamiliar with that type of algorithm, coming to the source file many years after the last time it was edited, etc. The reasons to need documentation are many, and even if the code “is so good it doesn’t need comments” that usually does not matter at all to the person reading the code, and that person still does need comments. Thinking of comments as an indicator of inferior code is a dangerous code golf mentality that ignores the fact that you write comments _for people_, especially people coming to the code in a way that breaks all the assumptions the code author was thinking when they decided not to write comments.

IshKebab 8y ago

Some code is complex enough to need a proper explanation. Maybe you just haven't encountered any. I guess it would be rare in CRUD or web apps, but when you start getting into algorithms... Look at Ryu for example. Good luck understanding that without comments or documentation: https://github.com/ulfjack/ryu/blob/master/ryu/f2s.c https://github.com/ulfjack/ryu/blob/master/ryu/f2s.c

u801e 8y ago

No matter how well the code is written, without comments, understanding why it was written is going to be difficult to determine.