Hacker News Reader

Most of what you described as needing documentation could be expressed as code (mixing multiple languages here to express the point more clearly)

const fn get_outer_height() -> Result<SomeErrorType, WeakReference<Number>>

- `const` makes it clear this doesn't mutate

- the function name says exactly what it does

- The return type makes it clear it can return an error

- The return value is typed in a way that makes it clear what the ownership is

Throw in a language like Rust that gives guarantees about thread safety and now the only thing left is if the API is stable or not. Which I would argue doesn't matter much at all since people will still end up depending on it regardless of the comment saying "This API might not be stable"

And the best part? My definition will never get outdated. If the assumptions change, the definition will also need to change (well, except for maybe the name)

You are absolutely right, and one should prefer languages that can give such guarantees wherever possible.

But often one doesn't have a choice. People still write software in inferior languages such as Javascript or Python, where you cannot even be sure about a return or parameter data type.

To add to what you're saying:

Quite often something is not obvious or trivial to someone who is examining a piece of code or using a library for the first time because it assumes the person already understands the context.

An example of what I mean: perhaps it is because I have a background in the sciences, but I assume that most properties have units. A property such as height certainly does have units. So is get_height() returning the height in pixels, inches, meters, or something else? I have also been bitten by graphics libraries that measure distances in unexpected (to me) way. Is the radius of the arc with line thickness 'n' using the inside radius, outside radius, center line, or something else? The person writing the original code may think the developer using their code down the road can test different assumptions, yet the reality is the number of combinations to test will rarely be trivial (and that is assuming they identify the correct parameters to test).

It's at the point where I refuse to even consider using libraries that leave out documentation for obvious things. Even comments like "gets the height" raises red flags since it is a demonstration that the author did not put any thought into what they are documenting.

I don't agree with this answer. I fully agree that documentation is important, needs to be correct and maintained. However, I do stand by the original poster saying that it is often a bad idea to enfroce javadoc style comments to autogenerate documentation. This often leads to low quality documentation.

Like you say, get_height is a trivial function, but still requires attention. Enforcing in-code docs is not going to help to have higher quality docs, quite the contrary. You often get low effort stuff, just to make the code checker happy.

And if you put in a peer review process to validate the in-code comment, it loses all power because you might as well use that step for decent documentation. get_height should be documented in a logical place, where it makes sense indeed, like grouped with get_width. But now you have the logical place to put your documentation, and the forced javadoc comment. That's double work, and one of them will be bad quality as a result of it.

Nobody is arguing for no documentation, but I am arguing for avoiding javadoc enforcements. My solution is much simpler: have a documentation check as part of the peer review process. Sure, have a template for the documentation, but don't make it strict. Ours is simple: all juniors are on documentation peer review as part of their onboarding. If they don't get it, it needs to be fixed.

Our peer review process is quite simple: is the documentation adapted, is there a relevant unit test (we actually have low UT coverage, we only do them for critical code and as part of bug fixing, so enforced frameworks make no sense for us), and naturally is the code quality itself ok

But many companies don't do those, yeah well thats how you get shit.

> get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects?

In my experience, if your documentation covers all these aspects it's guaranteed to be either wrong, misleading, or out of date on any of these details, and you better read the actual code to be sure.

In particular, the answer will often be "it depends on what the rest of the system does". Perhaps it delegates the actual calculation to an API, and this doc won't change when the API changes in a _mostly_ compatible way.

I mean, even with the best efforts given, code has bugs, words are vague, there's no way you should trust the dev who wrote the code to properly convey what it actually does.

Wouldn't it be more efficient to just read the source code? Also, the point the guy you're responding to is making is not that code shouldn't be documented, but that in-line documentation of this variety is not that great. You seem to be interpreting him to be saying that the code shouldn't be documented at all, which is not what he is saying.

It's true that there can be gotcha's in code which should be documented, but I don't think forcing a template on people is the solution. In fact, I wouldn't expect people to be better at documenting them with that in place.

Well, yes, you need to have manual or automatic checks for the presence of the template, and the correctness of the contents is often uncheckable by automated tests. But if things break and e.g. the filled-in documentation template incorrectly said "thread-safe: yes", it will be very easy to 'git blame' the culprit. That way you can at least slowly weed out the sloppy documenters, but I admit that this is tedious.

And, yes, I don't like this either and would like a better solution. But so far I didn't get any viable suggestions.