1. Comments that are effectively headers:
# If the user is foobar, do thing
user = User.find(current_user_id)
user.preload_bizbaz!(cache: false)
is_foobar = user.bizbaz.foobar.status == "yes"
if (is_foobar) { do_thing(user) }
Yes, you can read the 4 lines of code to see the "what' - the comment is duplicative. But when I'm skimming through a large codebase trying to find or understand something, these headers can be invaluable.2. Comments on dense code
# Matches any email like [email protected] (only .com, .net, .org email addresses)
return email.match(/^.*@.*\.(com|net|org)$/)
Yes I can that regex, but I can read that comment a lot faster.Here is the thing: Header comments are not really about explaining their following code. They are about reducing the lines you need to read to navigate through the code by a factor of 5 to 10. Huge time-saver, and helps a ton newcomers to become productive quickly.
// The following block should have the same
// result as this (simpler) code:
// <code>
// but for <reason> this version is better
This is great for things like opaque optimizations, things that mimic a library function except for one critical difference, blocks that become really convoluted to deal with special cases, and similar.I agree. However, "what" comments need a little more skill and judgement to know what to write and what to leave out.
Having a terrible memory helps develop that skill, because you kind of get a sense of what you'll want explained to you again in six months and what's hard to decode.
Regex is the worst language that everyone needs to know.
That always gets trotted out, but it's sort of like "don't write code unless you can guarantee the code won't have any bugs, so never write any code."
The trick is write code and comments, but be a little skeptical of both. If you're disciplined (especially with commit messages), it's usually pretty easy to figure out a mistake or omission after the fact.
"...only from %s domains..."
There are definitely places where that's hard or impossible and your regex code is a good example of that. I write a fair amount of C at the moment and you can have some pointer arithmetic that's not even that complicated, but a comment on it makes scanning through the function much simpler.
I'm mostly in agreement, so I'm going to focus on my disagreement too! ;)
This view is pretty common in the ruby community. So much so that I think they take it too far at times. I sometimes find myself reading a class that could have been a single 24-line method but is instead one method with method calls, each of which calls 0-2 more methods.
This style is good for when I'm trying to quickly understand what that class is supposed to do - I just read the top-level method that looks like:
thing = getThing()
munge { |i| thing[i] }
is_foobar?(thing)
But it's terrible when I need to understand what that function is actually doing - eg to debug it or to find some underlying function call I'm looking for. I have to bounce all over the file to mentally reconstruct a linear sequence of code which could have just been one function with some headers.Of course, this style is a reaction to impenetrable 500-line functions which are also terrible. I'd definitely prefer many small functions to that! I think it's a matter of judgement and experience to know whether some code is better as small stanzas with comments or small functions.
- a nice explanatory name to it
- if the functionality changes then it is more probable that the name would change
- the code is hidden away if you don't care about the why (maybe you are looking for something else)
I feel like there are a bunch of coding habits that work well for solo developers but not devs on a team.
Second one is not a good example, because I think it's a very common pattern and email.match with com|net|org provides enough context by itself. It's just bloat imo.
I generally prefer the word "context".
The trickiest aspects of writing and editing software tend to boil down to two subjects:
1. What's the underlying system we are trying to manipulate? How is its data structured, and what kind of loops and logic branches can be hijacked for our new functionality?
2. Where and when is our new code interacting with the underlying structure?
3. To tie the first two together, what data/functionality are we exposing to the user? How and when? What is the user?
Most contemporary programming over the last two decades has been focused on nouns. The last 5-10 years has seen a shift in popularity to verb-based (functional programming) paradigms.
We can find insight from noun-based programming to answer "what?", and verb-based programming is good at answering, "how?".
Neither really do a good job of answering "where?" or "why?". Those have to be peiced together like evidence in a crime scene, and by the time you figure it out, you've probably learned everything there is to know about the entire codebase.
Eg, were other options considered and this one chosen? Why? Is this piece of code non-standard or particularly clever? Why? Is this piece of code more complex than it seems like it needs to be? Why? Does this piece of have non-local dependency that may not be obvious at first glance? Are there security concerns with this piece of code which are non-obvious to a novice or an outsourced worker? Etc.
There's the old saying, "since debugging code is more difficult than writing it, then if you write the most clever code you are capable of, then you are by definition incapable of debugging it". Pretend you're explaining your code to future you who has forgotten why you did what you did and isn't clever enough to debug it.