[TheNewAndy]

That's an interesting assertion, but not one that matches the experience I've had.

It is one of those things that sounds "obviously true", but in practice I've found that it doesn't really live up to the promise. As a concrete example of this, having a plain text header file as documentation tends to mean that when people are reading it, if they spot a mistake or see that something isn't documented that should be documented, they are much more likely to fix it than if the documentation is displayed in a "prettier" form like HTML.

The problem with header files that aren't "well-written" tends to be that the actual content you are looking for isn't in there, and no amount of language tooling can actually fix that (and can be an impediment towards fixing it).

[tpoacher]

I'll second this in Java land. I much prefer reading the sources directly than javadocs. Though jshell also comes in handy.

[josephg]

I have the same experience a lot of the time with 3rd party rust crates. Doc.rs is amazing - but it’s rare that I’ll use a library without, at some point, hitting view source.

[josephg]

I know people look at me like I’m a heathen and a scoundrel, but I think a lot of software teams spend too much time trying to make things consistent. Where’s the ROI? There is none.

GitHub readmes? Bring on the weird quirks, art, rants about other software, and so on. I’ll take it all.

Don’t get me started on linters. Yes, there’s lots of things that should actually be consistent in a codebase (like indentation). But for every useful check, linters have 100 random pointless things they complain about. Oh, you used a ternary statement? Boo hoo! Oh, my JavaScript has a mix of semicolons and non semicolons? Who cares? The birds are singing. Don’t bother me with this shite.

Software is a creative discipline. Bland software reflects a bland mind.

[lazystar]

> Where’s the ROI? There is none.

> Oh, my JavaScript has a mix of semicolons and non semicolons? Who cares?

i had to refactor and port a javascript codebase that contained a mix of all of javascripts syntactic sugar, no comments anywhere in the codebase, and i was unable to ask the original devs any questions. the high amount of syntactic sugar gave me "javascript diabetes" - it was fun figuring out all the randomness, but it delayed the project and has made it extremely difficult to onboard new folks to the team after i completed the port.

painting is a creative discipline, and the mona lisa has stood the test of time because davinci used a painting style and materials that set the painting up for long term use.

a codebase without standards is akin to drawing the mona lisa on a sidewalk with sidewalk chalk.

[XorNot]

I don't like complaining linters. I do like auto fixing linters I can leave running in the background.