6 ms·
Wish the article went into a bit more detail on the thought process. Code absolutely can be written in a self documenting way, just that most people don't stru
by adam_arthur 4y ago
Wish the article went into a bit more detail on the thought process.
Code absolutely can be written in a self documenting way, just that most people don't structure their code like English/natural language. Also some languages have too much syntax bloat to be written effectively in a self documenting way.
I agree with the principle that some things are better expressed through documentation, such as motivations and higher level diagramming. But the average code base is so far from being self documenting, that the gap there should be closed first before moving on to external documentation.
External documentation creates a second source of truth that often falls out of sync with the code, so becomes a form of technical debt/maintenance burden.
The best way would be exporting docs from your codebase, and have all documentation related artifacts expressed alongside the code. Diagrams expressed in a programmatic DSL etc
- throwawaylala1 4y ago> The best way would be exporting docs from your codebase, and have all documentation related artifacts expressed alongside the code I LOVE Golang's approach to this [1]: - Documentation generation from code is built in to the language toolkit - There is a standard for writing the comments so all of them look the same across every project - It even supports code examples which are visible as a REPL in the generated docs When people ask "what's so great about Go?". It's stuff like that which is hard to succinctly describe but makes a huge difference in overall quality of Go code in the wild. [1]: https://go.dev/doc/comment https://go.dev/doc/comment
- pjmlp 4y agoSo basically what Common Lisp, Smalltalk, Java, Perl, Python and Ruby have provided before Go was a thing. Many of the Go features are only a win when the competition is C.
- doctor_eval 4y agoI can’t speak for the others, but Godoc is IME way better than JavaDoc, which is both hard to write, and hard to read inline due to all the f*ing HTML. More to the point, just because some platforms provide equivalent functionality doesn’t make the GP wrong.
- euroderf 4y agoA nice Javadoc touch that Golang could use is to break out the documentation of arguments and return values.
- throwawaylala1 4y agoSo here's an example of the string package: https://pkg.go.dev/strings https://pkg.go.dev/strings In what way would the JavaDoc @param/@return/etc annotations actually help? What Godoc has is more than suitable for the vast majority of cases.
- pjmlp 4y agoThey provide the parsing engine with better clues for the AST that is given to the JavaDoc agent (aka doclet), which allows to customize the document generation process.
- throwawaylala1 4y agoWhich didn't answer my question at all. Adding more structure to the AST with @param/@return/whatever doesn't make for better documentation. It's useless crap in a real world scenario.
- pjmlp 4y agoLet me guess, another ACME fan that like Rob Pike doesn't use anything fancy as editor, including syntax highlighting. That crap allows for tooling that Go will never have thanks community culture.
- doctor_eval 4y agoWith respect, the general level of day-to-day tooling for Go is way better than for Java. Go is designed to be easy to parse and easy to build tooling for. “That crap” is at least in part a reaction to the endless stream of DocTagFactoryFactoryFactories patterns that came out of the Java world. While I think Java is a decent language with a good ecosystem, I’m completely over the idea that the only way to do things is the Java Enterprise(tm) way.
- throwawaylala1 4y agoThis is why I said it's hard to succinctly explain. Non-programmers and bad programmers can't tell the difference between Go and Python (for example) in this context. The actual difference is very very significant.
- rich_sasha 4y agoYou see one screen's worth of code at a time. You can't glance the big picture from code because code is about here and now. With some error handling code, for example, briefly commenting what conditions lead to what exceptions goes a long way.
- adam_arthur 4y agoYou can certainly get the big picture if you abstract the codebase in such a way that top level operations are abstracted by functions. But of course it depends on the context and what you're trying to do. React/Vue is a good example. You have some Application component that has a set of sub components representing different regions of the page, which have their own subcomponents and so on. Makes it very easy to dive in from top down and drop into lower level abstractions as needed.