Hacker News Reader

Comment by brador | Hacker News Reader

Good code comments can help this. But as we all know the more you work on code the more useless comment blocks you're left with until in the end the comments are meaningless and redundant in your sphagettic coded mess.

Solution: Descriptive Variable Names. You'll always have variables, they're a foundation of any code base, and by naming them well they flow through the code describing what's happenening with 0 extra work needed.

With good variable names you can then pepper the code with good meaningful one line comments when needed.

View on HN

Yes. The solution to bad automation is good variable names. I can't agree more.

I strongly agree that naming variable is an effort worth the benefits, but naming stuff correctly is not 0 extra work. As a matter of fact, judging by how many people give crap names to their stuff, I'd it's one of the most difficult task of designing something.

Finding a name that is both descriptive enough and not overly specific, that describes the 'what', not the 'how', doesn't conflict with other concepts and is not a 20 words Java style keyboard breaker, requires quite a lot of effort.

I swear I have to start coding with a thesaurus. I mean even basic variable names are sometimes hard to find words for. Say I define a list i aggregate output into which is returned at the end of the function. Do I call it output, output_list, result, result_list, result_l, r_list, o_l, output_l, o_list, aggregate, return_value, file_list, path_list, directory_list, dir_list, dir_l....

There's so many possibilities, some of the utterly rank, some of them decent, and a fair amount of good descriptors, but which one is best?

And that's just the naming of one variable. Then there's function names, module names, package names.

Is there some guides on this or something?

I prefer to name things after the major operation that is done with/to them and what they are if that not coveyed by the type. This is very imporant for strings (or array of string, etc) as the type tells you little about what that string is/for.

Using your style, variables would be named something like directory_aggregate, filtered_names, etc.

> output_list, result, result_list, result_l, r_list, o_l, output_l, o_list, aggregate, return_value, file_list, path_list, directory_list, dir_list, dir_l....

You're making it too hard, use normal whole words, call it "result" and be done with it; it's a temporary local variable, its name simply isn't that important. Class and method names are far more important because they have much larger scope.

Here's the trick to naming things well, name them and move on and then when you have to come back later-which you always do-guess what the name is; if you named it well, you guessed right. If you guessed wrong, rename it to match what you guessed it would be. Over time your naming will get better.

> As a matter of fact, judging by how many people give crap names to their stuff, I'd it's one of the most difficult task of designing something.

You're absolutely right, the two hardest things in programming are naming things, cache invalidation, and off by one errors.

As the author of the piece I'm disappointed that after reading a 6 page article all you got was "use better variable names".

I have to ask: have you never worked in operations or did you not read the article or were you trolling HN?

Reply on news.ycombinator.com