Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

3
  • Thanks for the answer! Good documentation certainly sounds like a worthwhile investment of time and I always make sure to write good docstrings for my classes etc. In terms of the overall view of a library/piece of software etc, what are the best ways to document it? I understand if this is a 'there's many ways to skin a cat' type of question! Commented Dec 2, 2022 at 15:38
  • 2
    Many platforms suggest filling out specific documentation templates, e.g. JavaDoc no just for methods, but for classes, packages and modules too. But it's usually not a good idea to document every class and every package. As programmer-and-user in one you have a great chance of answering exactly the questions that led you to build that system in the first place. My advice is to pick one level above the class and write a coherent description of any artifact at that level that will be useful to you. Commented Dec 2, 2022 at 15:50
  • Religiously adding Javadoc comments to everything certainly isn't useful, but it's always a good idea to write a few lines of explanation any time you're doing something complex or making some assumptions. Any time you can anticipate your future self asking "why did I do that again?", you should pre-emptively answer the question for them. Commented Dec 5, 2022 at 4:35