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? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it change any of its parameters? Who deallocates the return value? Do you need to hold a lock somwhere?
Of course it might be a good idea to group together get_height, get_width, get_diagonal and get_depth if the above is all the same for those. But having no documentation just because you think it is trivial that get_height gets some height from somewhere just means that you are sloppy and didn't think of all of the above. So your code shouldn't be touched with a 10-foot-pole imho.
My solution, which I personally hate but know of no alternative to, is a documentation template for each function asking the above questions (depending on runtime and language of course) that I give people to fill in. Until they learn...
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)
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.
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.
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.
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.
And, yes, I don't like this either and would like a better solution. But so far I didn't get any viable suggestions.
Then as the code grows, you need to document the architecture, add small gotchas, etc.
At the end of the day, documentation wins.
Bridging the gap between a prosaic high level explaination (how do the parts work together?) and a fine grained explaination of each part (what does that part do?) can be a challenge. Rust solves this somewhat by allowing you to do module level documentation (that can essentially look like a blog post, only that the examples get checked when the code is tested) and it lets you link to different entites.
I would always prefer a well written blog post, if people were able to keep the examples working and the code up to date. But experience shows they are not.
I'd rather have generated documentation that is true than a blog post where half of the examples won't work, because nobody bothered to update the post after the code changed. The first might at times be barren if done badly, the latter is downright misleading.
You say "gets the height" is trivial, but that text tells not only what the function does, but also that the author couldn't think of anything else important to say. This is very different from no text at all, where you can't be certain if the author even thought about it.
IMO, enforcing an internal structure (AKA "you must document each parameter and the return value") is counter-productive, but enforcing the existence of the comment is very productive.
> Also it clutters the code with many highly trivial remarks.
I'd say that it "clutters" the code with markers for public elements and hard to understand ones. Those are actually valuable, and not clutter at all.
Anyway, if those markers are a large share of your lines, you may need to rethink your architecture. It's usually not valuable to have a lot of interface for trivial things.
Also, I don't tend to trust it as much, because it isn't actually what the program executes.
When I'm trying to read the source code I don't want to read about the source code -- I want to read the actual source code -- and if I keep coming across long multi-line idiotic comments then it breaks my flow and concentration.
I like the source code itself to be extraordinarily readable, with long and descriptive variable and method names, but I want it to be dense and packed into paragraphs of sense.
To the extent there are any comments at all they should be extremely short and completely clarifying -- they should not even partially overlap with information conveyed through function or variable names, for instance.
Maybe you don't know Rust, but it is a strongly typed language. If you go to a rust project and run `cargo doc --open` you will see exactly what the type system lays out. Sure if someone writes "changes the windows height and returns a new Window" on a change_window_height(height: Pixels) -> Window and it changes the windows width instead that is still wrong. But (A) you can click on "source" and see the actual code and (B) you are guaranteed that the function takes Pixels and spits out a Window
That being said I hate that kind of documentation in most other languages, not in Rust. In Rust it is basically an alternative view onto the same code with a (needed) emphasis on the realtions of the entities the type system describes. If there is prose that can be a nice extra, but cargo doc is even useful without a single comment.