Programming

Clear concise code that reads like documentation is the ideal. Good function and variable names, formatting, and encapsulation play into this. Tests should document and describe the system.

If it still isn't clear what the code is doing, and I'm all out of ideas (or time) for refactoring, a well placed, accurate comment is fine. It needs to be kept up to date like any other artifact in the project.

It's harder to keep comments accurate than code, since code can be executed and tested. I use them sparingly; when I've otherwise failed to write clean code, or the code is just so complex that it needs to be described.

Comments are just another tool in the toolbox. If they add clarity to the situation, by all means, use them.

If you can think of an expressive variable name that lets you skip a comment eg "employeeCount", instead of "e" // number of employees, do that.

I like both comments and long variable / function names. I also like it when people break functions down into excessively fine detail.

Why? Because deleting redundant lines is always easier than figuring out what is going on when you don't have the information you need.

I will name functions by just vomiting out my current train of thought about what the function needs to do. Sometimes it ends up being so long it runs off the page. Good. Now I know exactly what the function does, and anyone in the future will too. But more importantly, an obnoxiously long name draws the ire of everyone who reads it until someone comes up with a better name - usually me, when I'm not actively trying to write the code in the function body. As long as this isn't a public function in a library that is actively being referenced by hundreds of people, the change is easy with modern ide refactoring tools.

My philosophy is that anyone familiar with the code shouldn't need the comments to understand it, and anyone who isn't should be able to with the comments.

This means that I have semi long names like "this_variable_varies" would be about the max name size I would use. But I also use plenty of small functions and I use comments to explain big chunks of code with just a simple goal and method description.

I sometimes find my code a bit overly verbose, but I know I would rather see that then some code that I need to de-obfuscate mentally.

I try to write comments whenever what the code isn't obvious on its own. A "never write comments" proponent might argue that you should never write code that isn't obvious on its own, but that doesn't always work in practice

• Sometimes you have to write cryptic code for performance reasons
• Sometimes you have to deal with unintuitive edge cases
• Sometimes you have to work around bugs in 3rd party code
• Sometimes you are dealing with a problem that is inherently complex or unintuitive, no matter how you put it in to code

I find vague variable names exhausting. It adds not inconsiderable mental overhead when reading code, at least for me.

I don't like code, that isn't well documented. In fact, this has been my main source of frustration in the past and required the most time to deal with. Thousands of variables, hundreds of thousands of lines of code, how am I supposed to go through it somewhat fast, if there aren't any comments or pieces of documentation that are guiding my understanding? I can't spend half a year to just get a grasp of how the code works.

Comments (as well as docstrings and readmes etc.) provide higher level overviews that can guide you through the code rather quickly, even if it may be longer in terms of words or character count than the lines of code it describes, it may accelerate understanding tremendously. It's just a lot more effort to trace each variable and see what it does and how it interacts with others. This can quickly become exponentially hard to track.

I don't think it's necessary to comment each line of code, except in rare cases or maybe when setting up a class and describing the members and roughly how they're used,, but a few words here and there, at some higher or intermediate level, roughly describing what you want to do, can go a long way for others (and even yourself, when working on a project for several years). It's also already sufficient to just highlight the most important variables in a piece of code, when explaining it. Given that info, this steers your focus when reading the actual code.

"Speaking" variable/function/... names are also very useful. I don't care if it's a long name, as long as it's sufficiently expressive. E.g. "space_info" instead of "si". This helps to understand the code more quickly and reduces backtracking lookups, because you already forgot again what a specific variable does that you haven't seen for a while. My rule of thumb for variable naming: As consice, short and "essence grasping" as possible, but as long as necessary.

Ah yes, one of the major questions of software development: to comment, or not to comment? This is almost as big of a question as tabs vs spaces at this point.

Personally? I don't really care. Make the code readable to whoever needs to be able to read it. If you're working on a team, set the standard with your team. No answer is the universally correct one, nor is any answer going to be eternally the correct one.

Regardless of whether code comments should or shouldn't exist, I'm of the opinion that doc comments should exist for functions at the very minimum. Describe preconditions, postconditions, the expected parameters (and types if needed), etc. I hate seeing undocumented **kwargs in a function, and I'll almost always block a PR on my team if I see one where the valid arguments there are not blatantly obvious from context.

More people should try out literate programming. It is very powerful, especially for complex code and software you want to maintain in the long run.

Later on, I learned that an excess of comments is actually not considered a good practice.

Pointless or uninformative comments are not good, regardless of the quantity.

Useful and informative comments are always good, regardless of the quantity.

I learned that comments might be a code smell indicating that the code is not very clear.

When I'm looking at someone else's code, I want to see extensive, descriptive comments.

Good code should be so clear, that it doesn’t need comments.

That hits me like something a teacher tells you in a coding class that turns out to be nonsense when you get to the real world.

I'm not sure how others do it.

As I'm coding, the comments form part of my plan. I write the comments before the code. As I discover I've made incorrect assumptions or poor decisions, I correct the comments with the new plan, then correct the code to match the updated comments.

As a final step in coding, when I feel it is complete, I'll review comments to determine what should remain to help future me if I ever have to dig into it again.

Variable names should be reasonably memorable and make contextual sense, but that's it. That's what they exist for. Don't overload the purpose of anything I'm the code.

No short variable names, also no non-lewd variable names, life is nothing without suffering.

You can write comments, but you can't make your colleagues read them. They don't necessarily have to visit the originating file to read the docs.

Short variable names tend to lead different people to make different kinds of assumptions about the purpose and use of the variable. Those differences in understanding is where a lot of subtle bugs come from, or causes people to hit a dead end.

Just be clear and explicit. Its not gaming; you dont have to care about losing a couple extra frames to type out a few extra characters. Most IDEs have sufficient autocompletes so it's literally not even a problem in many cases.

My rule of thumb is, use short names if the context makes it clear. But do not make names too long and complicated (especially with Python :D). For me having unique names is also important, so I don't get confused. So not only too similar names are bad, especially if they all start like "path_aaa", "path_bbb" and such, then the eye can't distinguish them quickly and clearly. And searching (and maybe replace) without an IDE is easier with unique and descriptive names.

Sometimes its better to come up with a new name, instead adding a modification and make the name longer. This could be in a for loop, where inner loops edit variables and create a variation of it. Instead adding something like "_modified", try to find what the modification is and change from "date" to "now" instead "date_current".

Nothing wrong with a, i, s and x.