6 ms·
> If there is a need to comment the code all over the place, to me it means that the code is maybe not as good as it should be :-) If good code was enough on i
by bottd 7mo ago
> If there is a need to comment the code all over the place, to me it means that the code is maybe not as good as it should be :-)
If good code was enough on its own we would read the source instead of documentation. I believe part of good software is good documentation. The prose of literate source is aimed at documentation, not line-level comments about implementation.
- WillAdams 7mo agohttps://diataxis.fr/ https://diataxis.fr/ (originally developed at: https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/) --- divides documentation along two axes: - Action (Practical) vs. Cognition (Theoretical) - Acquisition (Studying) vs. Application (Working) which for my current project has resulted in: - readme.md --- (Overview) Explanation (understanding-oriented) - Templates (small source snippets) --- Tutorials (learning-oriented) - Literate Source (pdf) --- How-to Guides (problem-oriented) - Index (of the above pdf) --- Reference (information-oriented)
- zenoprax 7mo agoI've been trying to implement this as closely as possible from scratch in an existing FOSS project: https://github.com/super-productivity/super-productivity/wiki https://github.com/super-productivity/super-productivity/wik... Even with a well-described framework it is still hard to maintain proper boundaries and there is always a temptation to mix things together.
- ramses0 7mo agoREADME => AGENTS.md HOWTO => SKILLS.md INFO => Plan/Arch/Guide REFERENCE => JavaDoc-ish I'm very near the idea that "LLM's are randomized compilers" and the human prompts should be 1000% more treated with care. Don't (necessarily) git commit the whole megabytes of token-blathering from the LLM, but keeping the human prompts: "Hey, we're going to work on Feature X... now some test cases... I've done more testing and Z is not covered... ok, now we'll extend to cover Case Y..." Let me hover over the 50-100 character commit message and then see the raw discussion (source) that led to the AI-generated (compiled) code. Allow AI.next to review the discussion/response/diff/tests and see if it can expose any flaws with the benefit of hindsight!
- AdieuToLogic 7mo ago> If good code was enough on its own we would read the source instead of documentation. An axiom I have long held regarding documenting code is: Code answers what it does, how it does it, when it is used, and who uses it. What it cannot answer is why it exists. Comments accomplish this.
- eru 7mo agoAn important addendum: code can sometimes, with a bit of extra thinking of part of the reader, answer the 'why' question. But it's even harder for code to answer the 'why not' question. Ie what were other approaches that we tried and that didn't work? Or what business requirements preclude these other approaches.
- 1718627440 7mo agoI don't think this is enough to completely obsolete comments, but a good chunk of that information can be encoded in a VCS. It encodes all past approaches and also contains the reasoning and why not in annotation. You can also query this per line of your project.
- eru 7mo agoGit history is incredible important, yes, but also limited. Practically, it only encodes information that made it into `main`, not what an author just mulled over in their head or just had a brief prototype for, or ran an unrelated toy simulation over.
- 1718627440 7mo agoIf you throw away commit messages, that is on you, it is not a limitation of Git. If I am cleaning up before merging, I'm maybe rephrasing things, but I am not throwing that information away. I regularly push branches under 'draft/...' or 'fail/...' to the central project repository.
- 7mo ago
- wvenable 7mo ago> If good code was enough on its own we would read the source instead of documentation. That's 100% how I work -- reading the source. If the code is confusing, the code needs to be fixed.
- kalaksi 7mo agoConfusing code is one thing, but projects with more complex requirements or edge cases benefit from additional comments and documentation. Not everything is easily inferred from code or can be easily found in a large codebase. You can also describe e.g. chosen tradeoffs.
- habinero 7mo agoThere's no way around just learning the codebase. I have never seen code documentation that was complete or correct, let alone both.
- actionfromafar 7mo agoBut the documentation can really help in telling why we are doing things. That also seeps in to naming things like classes. If that were not so, we'd just name everything Class1, Class2, Method1, Method2 and so on.
- samplifier 7mo agodef reallyDumbIdeaByManagerWorkaroundMethodToGetCoverageToNinetyPercent(self): """Dont worry, this is a clear description of the method. """ return False
- TuxSH 7mo agoYou exaggerate, but in this situation, I think putting a link to a Jira ticket or Slack convo (or whatever) as comment is best
- palata 7mo ago
- necovek 7mo agoHaving "grown up" on free software, I've always been quick to jump into code when documentation was dubious or lacking: there is only one canonical source of truth, and you need to be good at reading it. Though I'd note two kinds of documentation: docs how software is built (seldom needed if you have good source code), and how it is operated. When it comes to the former, I jump into code even sooner as documentation rarely answers my questions. Still, I do believe that literate programming is the best of both worlds, and I frequently lament the dead practice of doing "doctests" with Python (though I guess Jupyter notebooks are in a similar vein). Usually, the automated tests are the best documentation you can have!
- habinero 7mo ago> If good code was enough on its own we would read the source instead of documentation. Uh. We do. We, in fact, do this very thing. Lots of comments in code is a code smell. Yes, really. If I see lots of comments in code, I'm gonna go looking for the intern who just put up their first PR. > I believe part of good software is good documentation It is not. Docs tell you how to use the software. If you need to know what it does, you read the code.
- ninalanyon 7mo ago> If you need to know what it does, you read the code. True. But If you need to know why it does what its does, you read the comments. And often you need that knowledge if you are about to modify it.
- palata 7mo agoDo you have an example of such knowledge that you need to get from the comments? I have been programming for 20 years, and I genuinely don't see that much code that is so complex that it needs comments. Not that it doesn't exist; sometimes it's needed. But so rarely that I call it "comments", and not a whole discipline in itself that is apparently be called "literate programming". Literate programming sounds like "you need to comment pretty much everything because code is generally hard to understand". I disagree with that. Most code is trivial, though you may need to learn about the domain.
- tonyedgecombe 7mo agoMost of my comments related to the outside world not behaving quite as you would expect. Usually something like the spec says this but the actual behaviour is something else.
- EraYaN 7mo agoBecause the why can be completely unrelated to the code (odd business requirements etc). The code can be known to be non-optimal but it is still the correct way because the embedded system used in product XYZ has some dumb chip in it that needs it this weird way etc. Or the CEO loves this way of doing things and fires everyone who touches it. So many possibilities, most technical projects have a huge amount of politics and weird legacy behavior that someone depends on (including on internal stuff, private methods are not guaranteed to not be used by a client for example). And comments can guard against it, both for the dev and the reviewer. Hell we currently have clients depend on the exact internal layout of some PDF reports, and not even the rendered layout but that actual definitions.
- Verdex 7mo agoI do read the code instead of the documentation, whenever that is an option. Interesting factiod. The number of times I've found the code to describe what the software does more accurately than the documentation: many. The number of times I've found the documentation to describe what the software does more accurately than the code: never.
- crazygringo 7mo agoYou seem to misunderstand the purpose of documentation. It's not to be more accurate than the code itself. That would be absurd, and is by definition impossible, of course. It's to save you time and clarify why's. Hopefully, reading the documentation is about 100x faster than reading the code. And explains what things are for, as opposed to just what they are.
- Verdex 7mo agoClearly. Crazy thing. Number of times reading the source saved time and clarified why: many. Number of times reading the documentation saved time and clarified why: never. Perhaps I've just been unlucky? EDIT: The hilarious part to me is that everyone can talk past each other all day (reading the documentation) or we can show each other examples of good/bad documentation or good/bad code (reading the code) and understand immediately.
- crazygringo 7mo ago> Number of times reading the documentation saved time and clarified why: never. OK, so let's use an example... if you need to e.g. make a quick plot with Matplotlib. You just... what? Block off a couple weeks and read the source code start to finish? Or maybe reduce it to just a couple days, if you're trying to locate and understand the code just for the one type of plot you're trying to create? And the several function calls you need to set it up and display it in the end? Instead of looking at the docs and figuring out how to do it in 5 or 10 min? Because I am genuinely baffled here.
- 7mo ago