This is the same old nonesense:

This is bs. As far as I'm concerned, anybody who says this is just trying to justify being lazy. Would you rather work in a code base that is heavily documented such that you know where you need to make your updates or your "self-documenting" code base? The non-documented code base assumes that whoever worked on it did a good job. That is a very generous assumption.

For those of you that use vue/vuex, I have a few questions for you:

1) Thoughts on asyc store actions?
2) Thoughts on one mutation per one store action?
3) Thoughts on multiple mutations per single store action?

My thoughts on 2/3... if you have a store action that is triggering multiple mutations you will inevitably run into a many-to-many relationship between store actions/mutations. It's going to make it much harder to debug who is really triggering the mutation when its in > 1 place (and in a large app, that could realistically be many places). If you keep it in a 1:1 relationship (one store action will only mutate one state value) it makes it far easier to debug even in a large app.

I think too many comments can be worse than no comments.

It's a tricky thing to master. Your code should be as readable as possible without comments, but then you should also sprinkle some comments in the code to understand the logic better, explain business logic, background information, etc.

The main problem with comments imo is that they need to be maintained with your code. This gets exponentially harder when the volume of comments goes up.

You come at the king, you best not miss

Where are y'all taking this typing test btw, I must have missed it?

I installed Windows Subsystem for Linux and Ubuntu for my Windows 10 home laptop last night. It's pretty cool. I now seem to have the GOAT computer where I have windows when I want/need and also a Linux terminal. What super powers does this actually do for me though? I feel like I'm probably never going to use it. I do all my programming (Java, C#, and Python) in IDEs...

Imo it's not that great if you already just use git bash on windows.

The problem I had with self documented code or the whole “the code IS the documentation dummy” view is that the can only tell you what is going on, not why.

There's no 'can be' about it. Too many comments is terrible. I can't think of one top notch dev I know who doesn't feel the same way.

Ideally code should read like a script. Do this, then do that. If this, do that. Etc. In a world of > 8 char variable and function names - you don't need comments for that. I generally only make comments when I do something that feels a little awkward or counter-intuitive - and then only after thinking long and hard if there's a less awkward way to do whatever I'm doing.

My standard is if I think myself coming back in 6 months will be confused, I might make a brief comment.

Even if I am writing a framework, I will generally make a one-line comment over each method definition. I've never met anyone who actually uses js-docs, and the comments are brittle and take up a ton of space.

Exactly. A concise "Process <stuff> in <some_way> to accomplish <some_business_goal>" can be invaluable.

Yea it probably wouldn't help much for just your one off commands, but it seems powerful in that it's like a full blown environment. Like you can apt-get install new software to the Linux subsystem and use it like a full blown computer. You can bring up graphical windows as well. That said though, as I probably implied before, I'm not much of a Linux fanboy, Windows suits 99% of my needs, so I'm not sure how much that stuff does for me.

In modular programming - "what" is the method names and variable names, "why" is the module names. Generally. Method names can also express why.

I don't think it's that tricky, actually. If you need comments to explain what specific code is doing, the code needs to be rewritten.

Comments are appropriate for high-level concerns like explaining architecture, the reason module X was chosen, or the history behind some oddly chosen name.

As a rule of thumb, comments are the kind of thing you'd say to someone before you opened up a tex editor: "Oh, before we get into this, let me tell you X....". So good comments typically wind up in README files or at the top of a file. With occasional exceptions for things like naming oddities within the code:

To be fair, the last production code I wrote more fancy than batch files or Nginx confit files was in COBOL so naming standards where closer to Hungarian than anything else...

I'll add that comments aren also not documentation in this sense - you'd want a design document and some kind of spec that explains how the whole thing is organized and why, not a bunch of inline comments scattered around the code base.

If your app can't be described in a README, your app is probably too complicated and should be broken up. Design doc and spec are fine to tell devs how to built the app, but then should immediately be thrown away - as they're instantly out of date and will inevitably lead to confusion.

Yeah, github readme’s are a great solution to giving context to a program. Getting people to write them still a problem for teams with no process.

Right - but it's infinitely easier to get devs to write a readme than getting them to write a spec in Word or something, then store them off somewhere, and keep them up to date. With a readme the lead dev is a lot more likely to keep it up to date imo because it's right there with the code. The dev doesn't want to look stupid, nor get constantly bugged because things in the readme don't line up with current code.

But mostly you know where the README lives. A dev that's new to the project should never have to go on a scavenger hunt to find documentation. There isn't always someone to tell them where the docs are, and over time everyone forgets. At least it always winds up that way at most places I've worked.

Sure but README != inline comments. And breaking up a monolith into separate apps or repos doesn't remove the complexity - someone still has to understand how the apps interact. If anything, having multiple apps and repos is more likely to require documentation outside of repos, since it's unclear where the interaction between apps should be documented.

Markdown vs Word is orthogonal to README vs design doc/spec which is also orthogonal to in-repo vs out-of-repo storing of documentation.

If I use a node util that uses 10 other first-level sub-packages, it doesn't have to explain to me how it uses all those sub-packages. I can go to the readmes of those packages if needed.

I know OS is different with a big internal app. But if you modularize well, it gets close to that ideal.

This isn't typically how a large system is structured though - if you have 100 UI apps and 100 microservices, it may or may not obvious how they are working together and which are the important apps that are coordinating the other apps and which are apps and services are features and so on. Package management dependencies are easy to manage (well for some definition of easy), but service and data dependencies are unlikely to managed this way. You're also assuming that everyone is using node - the larger the system gets and the more it embraces the microservice culture/architecture, the more unlikely it is that you'd be familiar enough with the dependency management system used by every single component in your system. Often you have applications that are collaborating and communicating in fairly intricate ways - consider all the components in a complex machine learning data pipeline - that are not obvious when you're looking at the pieces in isolation.

Another issue is that the larger the system and the more complex the domain, the greater the likelihood that you'd need to collaborate with domain experts on documentation, where external systems like wikis or issue-tracking systems easily win over markdown stored in repos.

I personally favor mono-repo and having all technical design doc in that repo so that code changes and documentation changes can be reviewed together but what typically happens when you have lots of repos, lots of applications, which also means lots of different teams doing their own thing without anyone else knowing, is that things leak outside of repos as people build and use their own documentation solutions and are no longer aware of how other teams are doing things.

My company is too big. We had 100s of monoliths before microservices were even a term. We have endless useless wikis and competing forms of documentation, all of which are instantly out of date. It's hell. At smaller large corps I've worked for it's a milder version of the same hell.

I have zero faith a large, non-tech-high flyer company can ever make over-arching documentation work for anything other than aiding communication during active development. Or something like a cookbook for a microservice platform - which by necessity must work and be kept up to date as long as the platform is being maintained.

So I just try to push the stuff I think will actually work for the longest % of the product lifespan.

I think Jeff Bezos famous amazon mandate is relevant here, and is a counterpoint to your last paragraph.

Counter-counterpoint: Google & Facebook

Also, 1) lots of companies are actually smaller than an Amazon team. 2) monorepo does not dictate anything about the run-time architecture of your system.

Me neither but my point wasn't that you need this, merely that in situations where you need actual documentation, it's generally unlikely that inline comments sprinkled here and there will suffice. It's a counterpoint to the argument that coders complaining about useless comments are just lazy bums who are refusing to document stuff. The critical flaw there is conflating comments with documentation to inflate the importance of comments.