3 ms·
What I have trouble with is high-level comments. I very rarely find myself wanting to add comments to an individual file but very often to an entire sub-system.
by ng12 8y ago
What I have trouble with is high-level comments. I very rarely find myself wanting to add comments to an individual file but very often to an entire sub-system. Comments like "this package has classes related to Foo which is like Bar except Baz. Foos are populated from this location and are used with service Qux". I struggle to find appropriate places for these kinds of comments.
- ninthcat 8y agoYou can add a README.md file for a folder that you want "comments" for.
- neurotrace 8y agoI'll second this approach. I started doing this recently and current me has already thanked past me for doing it.
- yawaramin 8y agoMany languages have a place for these 'module level' comments. The ones that I know of: - Java has package-info.java - Scala has package.scala - JavaScript/TypeScript has the @file annotation in the doc comment at the top of the file - OCaml has the doc comment at the top of the file When you want to document an entire sub-system, it makes sense to put the documentation in that sub-system's root module.
- AstralStorm 8y agoAnd Python has __init__.py in the module.