white-spaces are code too...
It's great, your code works in production and is fast enough.
Congratulation, but...
- Is it readable enough?
- How easy is it for a new developer to pick it up and make all the sense?
- Does reading through the code present a good mental model of the system built?
This not an exhaustive list, but if answer to any of the above question is NO, then you should consider revisiting and making a few cosmetic changes.
Here are a few pointers that I follow when writing/reading code
white-spaces
- white-spaces are code too
- leave a blank line between method definitions
- a blank line when there is a changes in context within method body
indentation
- indent code well
follow consistent indent length, 2 spaces or 4 spaces
be consistent with use of tabs or spaces, choose one and stick to it across the team(s)
variable and method naming
- use concise and meaningful names
variable names should reflect the value they refer
method names should reflect the process / business logic contained
documentation
- unless it is a framework, module, class, method, variable names should be self documenting without need of additional documentation
comments should not be a tool to justify messy code segments
design the code
- every code is a piece of art uniquely conceived by it's developer
visualise the interactions between objects before beginning to code
visualise message exchanges needed before beginning to code
right abstraction
- abstraction does not mean hiding the complexity detail
know the behavioural traits to model
have a api spec to refer to
know before hand methods, variables, constants to expose
do not make decisions based on speculations
requirements are the corner stone
language idioms
- make use of language idioms
Ruby Example: [1, 2, 3, 4].sum v/s [1, 2, 3, 4].each {|ele| sum = sum + ele}
Code for Humans
Cover Image Credit: Unsplash
Top comments (21)
This is very useful for people, like me, that are not sure if their intuitive code spacing is actually correct. Thank you!
Just one suggestion: can we start saying "a new person" or "a new developer" instead of "a new guy"? Some might think it's silly and not very important but it does contribute to "non-guys" feeling less welcome in the industry.
Thanks Anabell-o, I have made the change.
I use the term "employment units", and nobody has complained.
Try using "resources", instead.
Bit impersonal for me
And "employment units" isn't?
Oh, wait. That's the joke, right? 😊
Me too. "guys" is still my go to expression to address a group. But by caring we can change. Thank you! :D
To be completely honest I don't see a problem with using "guys" when referring to a group because it is implied that there could be gals included in the group. However, I will say that English is becoming very confusing to learn properly, but my opinion is this: if someone doesn't like slightly gendered connotations, go learn Spanish. :P
Hi TMcSquared! First, the original wasn't using "guys" to refer to a group of people, but "new guy" which would never apply to a non-male person. Don't you think it's suspicious that gals have to be implied, but men are always explicitly mentioned? Second, people that identify as male have no problem feeling included by "guys" because it includes them in every case, it's not the same for other gender identities. And if you take into account that this industry (and many others) is known for not being as welcoming as it could be to other non-guy identities, and the efforts being made to change that, avoiding unnecessarily gendered words is a big step. Language shapes the way we process reality. Changing the way we express ourselves is not something minor, it has the power to change our perception, and ultimately the world.
Oh, and I'm a native Spanish speaker, so I know how gendered it is and how it reflects hispanic perceptions.
GuysPeople get triggered with anything these days lmao.Very good list.
However I have to disagree with the statement that "white-spaces are code". White space is critical to properly formatting code, but what is "proper" might not be the same for every language, framework, project, team, etc. Which is why, I think, white space should never be part of the syntax.
it's only human to ignore what is not core.
Language keywords, data-structures, statements and expressions clearly are code and would never be compromised on.
I agree this is not syntax, and would be different for every language.
My point is let's start treating white-spaces as code too. Let the style guides reflect this, let there be a mention somewhere for the teams to refer.
Example:
Ruby
Elixir
I started learning Go a few months back, the language has first class support for this with the gofmt utility. The only purpose it serves is formatting the code, because it's necessary and important.
All across the team, members should follow same scheme when it comes to using white-spaces.
Scenario: Don't have half the team using spaces and other half using tabs for indents. This is only possible if team views the white spaces in the same light as the actual code.
Fully agree
From wikipedia:
The term "man" (from Proto-Germanic *mannaz or *manwaz "man, person") and words derived from it can designate any or even all of the human race regardless of their sex or age.
Not meaning to offend anyone here but we've lost our sense of history when we don't understand the meaning or origin of the words we use daily. The argument of why is it called man is so fueled by hate I wonder, about those who insist it's patriarchal archetype, if they have heard the phrase choose your battles
I agree that history is important but we're not talking about a historical document nor are we talking about a completely male audience. Considering the context, using "developer" instead of "guy" made more sense for the audience of this article, especially when many of the non-guys in that audience feel excluded. Language matters too.
This is all solid advice. I recommend your team adopts a style guide to ensure consistent style and readability.
If in doubt, there are some solid style guides out there you can follow, e.g.:
Airbnb JavaScript Style Guide
Great article!
I would add:
In general, consistency is more important than other considerations. Before editing code, it is good to have a look around, gasp what is the general style and try to mimmic it as much as possible.
Linting and automatic formating makes life better for all the team. Discussions should be about architecture, not about semicolons.
Maybe I just don't understand what you mean here, but I would say especially in a framework you need to be careful with naming things and making code self-documenting. Frameworks just need documentation in addition to this, so that the flow of the framework can still be followed even without looking at the source directly.
One other thing I would add in the documentation section: Code (even messy code) will tell you what's going on, so comments should describe the why, not the what.
What I meant to say is, unless it's a framework, self-documenting code is enough, no need to have comments most of the time.
Frameworks too would follow the naming conventions, and on top of this they would also have the documentation/user-guides and comments that explicitly state the intent of code.
I would avoid adding too many comments within the domain/application specific projects, except when these are actually needed, like when there's a special branching instruction to handle rare edge case. The Why not the What.
I will try to rephrase this for more clarity. Thanks :)
Very nice article! Moreover, I found this one - another article about mistake on programming (its specific javascript on that article).