[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.

[sim7c00]

for most rust ive done (not tons) the docs were very basic as onky auto generated with minimal content. totally useless, have to read sources to find out what is in there. auto documentation to me ia just ti satisfy people who need to tick all of these boxes and want to do with minimal effort. has dox has tests etc. such artitude never leads to quality.

[bluGill]

Useful documentation is impossible for the developer to write - they are too close to the code and so don't understand what the users (either api users or end users) need to know. Developers agonize over details that users don't care about while ignoring as obvious important things users don't know.

[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.

[lazystar]

> auto fixing linters

any advice on how to implement an auto linter in an old codebase? i hate losing the git blame info.

[XorNot]

I use a .git-blame-ignore-revs file. So if you run the fix once, dump that commit in the file and use it when you use git blame, it'll exclude blame in that commit.

https://www.stefanjudis.com/today-i-learned/how-to-exclude-c...

[lazystar]

awesome, ty!