@simon anyone who makes that argument is just too lazy to write documentation and therefore probably shouldn't be writing code either.

@simon https://briefs.video/videos/what-is-self-documenting-code/

@simon documentation is one of those things that because it is in general so bad, some people think documentation is unneccesary. It's not the case. Good documentation provides a lot of value, but it's difficult to find it.

@simon Code is "what". Documentation is "why".

@simon The idea that code can serve as documentation is more a rebuttal to what's taught in school i.e. add a comment before every line. I need a comment before every line in class because I want to know if the student understands.

The problem with inline documentation outside of class is that it can become out of step with the code, the goal of saying the code is the documentation is to have programmers write clear, rather than clever code.

@simon hmm, I think the Rust docs are pretty good (read Vec or something). Sometimes, the documentation is perfunctory. When there's a long comment, you know something is up. That helps a lot.

Compare Vec::with_capacity() to Vec::capacity(). https://doc.rust-lang.org/src/alloc/vec/mod.rs.html#949

@simon I have a hard time to get our devs writing documentation. We agreed on mkdocs, so that it is as easy and naturally to have the docs along the code base and you just can check it in. Right now, it turns more into the direction, that I document the why there... at least marketing now uses this also for their content creation (after translating it to 'less technical').

@simon if there was an easy translation between source code and intent, the plain description of intent would just be the code and we wouldn't have needed developers.

@simon Depends very much on the code.

I like it if the code is very clear about WHAT is does. And comments or docs explain WHY it does it that way.

Because that knowledge WILL be lost over time.

@simon the source code being readable is one of the reasons I've been jumping around languages lately, been messing with Rust/Godot and now Mojo Lang which is kind of a mix between some Rust ideas and a Python Superset.

@simon caveat: if the alternative to reading the code is deciphering the requirements analysis that is partly in Sharepoint (in Powerpoints!), partly in Azure DevOps tickets and partly in someone's head.... 🙃 /s

@simon

Everyone knows the real comments and documentation are stashed and hidden in git commit comments. I'm kidding, but many companies rely on this information in the ticket system.

Depending on the language, Inline code comments can be a security risk. I have used comments in Java and C# to help design an exploit for the software.

Edit: ctrl+f todo (find all the gaps lol.)

Also, isn't AI now the solution for just-in-time code documentation?

@simon The thing that makes me sad about this discussion is that it has gone on since the late 1950s; there have not been any new arguments in 30 years and the only good explanation was Knuth’s Literate Programming book but nobody ever really understood it.

@simon

If you do not have at least as many comments in your source code as the actual compiliable source code, you are making a mistake.

I should clarify: when I talk about documentation here I'm not talking about code comment style docs - I'm talking about "this is how to use this library / API" docs

If your code is clearly written and nothing else ever needs to call it then I don't particularly mind if there's no additional documentation - but if I'm expected to use call your library from my own code I'm very much not keen on being told I have to read all of that code myself just to use it!