3 ms·

My point is that people should be encouraged to keep code comments to a minimum, and always strive to first rewrite the code so that it is clear (well-chosen va

My point is that people should be encouraged to keep code comments to a minimum, and always strive to first rewrite the code so that it is clear (well-chosen variable names, etc). LP does the opposite: it encourages verbosity, and tangential discussion.

Jtsummers 7y ago
My point is that literate programming isn't about comments. Comments are asides, they aren't the core focus of what's being read, the code is. Literate programming is about documentation, which should be kept concise, but not necessarily minimal. As to whether this leads to tangents or not, that's up to the authors to determine how to organize. Appendices or rationale sections are a great way to separate the core focus from what others may see as extraneous.
- Myrmornis 7y ago
  Yes, sorry, I did understand that that was your point. I just feel very strongly about the tendency, for people (especially new programmers) to be told that it's important to comment code heavily. Yes I've never seen a good solution for documentation in the teams I've worked in on larger systems/codebases. I'm not really a believer in documentation that evolves in a separate git repo (or god forbid, in Confluence) for the obvious reason that it gets even more stale than documentation that evolves in the same git repo. So that would put me in favour of your position here. But, how can documentation (with appendices or rationale sections) be interleaved with code without destroying the ability to read the code? I've tried RWeave in R a long time ago, and I've even collaborated and published on a literate programming tool, and I have always come back to the conclusion that I want to read code with the minimum of intervening prose. So my position is documentation should absolutely be written and maintained, it should be in the same git repo as the code, it should be in a separate file (not in comments or docstrings or automagically weaved sections using some special syntax), it should be written tersely and without much personality, and code reviewers should request documentation updates if a PR renders some documentation stale or requires new documentation. So I'm pro documentation, anti LP, and pro minimal code commenting.

Jtsummers 7y ago

My point is that literate programming isn't about comments. Comments are asides, they aren't the core focus of what's being read, the code is. Literate programming is about documentation, which should be kept concise, but not necessarily minimal. As to whether this leads to tangents or not, that's up to the authors to determine how to organize. Appendices or rationale sections are a great way to separate the core focus from what others may see as extraneous.

Myrmornis 7y ago
Yes, sorry, I did understand that that was your point. I just feel very strongly about the tendency, for people (especially new programmers) to be told that it's important to comment code heavily. Yes I've never seen a good solution for documentation in the teams I've worked in on larger systems/codebases. I'm not really a believer in documentation that evolves in a separate git repo (or god forbid, in Confluence) for the obvious reason that it gets even more stale than documentation that evolves in the same git repo. So that would put me in favour of your position here. But, how can documentation (with appendices or rationale sections) be interleaved with code without destroying the ability to read the code? I've tried RWeave in R a long time ago, and I've even collaborated and published on a literate programming tool, and I have always come back to the conclusion that I want to read code with the minimum of intervening prose. So my position is documentation should absolutely be written and maintained, it should be in the same git repo as the code, it should be in a separate file (not in comments or docstrings or automagically weaved sections using some special syntax), it should be written tersely and without much personality, and code reviewers should request documentation updates if a PR renders some documentation stale or requires new documentation. So I'm pro documentation, anti LP, and pro minimal code commenting.