4 ms·

> code can be quite grokkable with little documentation Indeed, the code _itself_ can often be understood from reading the code. Documentation is for everythin

by scubbo 3y ago

> code can be quite grokkable with little documentation Indeed, the code _itself_ can often be understood from reading the code. Documentation is for everything _else_ - explanation of the choices made and motivations when picking a particular design (so that they can be re-evaluated when a redesign is considered), customer-facing onboarding guides, runbooks for how to carry out operational tasks, and so on. That is - https://brooker.co.za/blog/2020/06/23/code.html https://brooker.co.za/blog/2020/06/23/code.html

munk-a 3y ago
This is quite true and one of the reasons I hate auto-doc comments. If a function tells me that an input is an integer there's no reason to repeat that information in the header above the function unless that information is then being parsed to produce a more readable form of documentation (i.e. as JavaDoc was originally used). Additionally I personally, though I am happy to concede that it may benefit some people, loathe "$documentId The ID of a Document" style comments. If you are adding more information above and beyond what is relevant from code - especially if that information relates to why you chose this approach over a different one - that is useful information. Documentation in the form of project planning documents, SOWs, data diagrams etc... - that stuff is always quite valuable, especially since it comes with an understanding that it was valid at a certain point in time (and may no longer be valid) but belies underlying decisions in how things were built and why.
- jonwest 3y ago
  The only justification I can give to “$documentId - The ID of a document” style comments would be if they are alongside comments that actually give context. If there are 5 parameters, and 3 of them are helped with a bit of context, then adding superfluous comments to the other two makes sense because that in itself is a piece of documentation (parameters needed for a function or class). If all of your comments are like that though? Gross.

by scubbo 3y ago

munk-a 3y ago

This is quite true and one of the reasons I hate auto-doc comments. If a function tells me that an input is an integer there's no reason to repeat that information in the header above the function unless that information is then being parsed to produce a more readable form of documentation (i.e. as JavaDoc was originally used). Additionally I personally, though I am happy to concede that it may benefit some people, loathe "$documentId The ID of a Document" style comments. If you are adding more information above and beyond what is relevant from code - especially if that information relates to why you chose this approach over a different one - that is useful information. Documentation in the form of project planning documents, SOWs, data diagrams etc... - that stuff is always quite valuable, especially since it comes with an understanding that it was valid at a certain point in time (and may no longer be valid) but belies underlying decisions in how things were built and why.

jonwest 3y ago
The only justification I can give to “$documentId - The ID of a document” style comments would be if they are alongside comments that actually give context. If there are 5 parameters, and 3 of them are helped with a bit of context, then adding superfluous comments to the other two makes sense because that in itself is a piece of documentation (parameters needed for a function or class). If all of your comments are like that though? Gross.