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 wellfollow 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 namesvariable 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 documentationcomments 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 developervisualise 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 detailknow 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 idiomsRuby 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)
- LocationBarcelona
- WorkSoftware Engineer at Typeform
- Joined
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.
- LocationPune, India
- WorkCo-founder and Director at Eloquent Studio Private Limited
- Joined
Thanks Anabell-o, I have made the change.
- LocationThame, Oxon, UK
- EducationM.Eng. Aeronautical Engineering, City University, London
- WorkTechnical Product Director at Consonance
- Joined
I use the term "employment units", and nobody has complained.
- LocationThame, Oxon, UK
- EducationM.Eng. Aeronautical Engineering, City University, London
- WorkTechnical Product Director at Consonance
- Joined
Bit impersonal for me
- LocationBeaverton, OR
- EducationSome
- WorkApplications Engineer at FLIR Systems, Inc.
- Joined
And "employment units" isn't?
Oh, wait. That's the joke, right? 😊
- LocationWaco TX area
- EducationHighschool
- WorkSon at Mom/Dad
- Joined
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
- LocationBarcelona
- WorkSoftware Engineer at Typeform
- Joined
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.
- LocationPhilippines
- WorkSoftware Engineer @ Iress
- Joined
Guys People get triggered with anything these days lmao.
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 ofwhy is it called man is so fueled by hate I wonder, about those who insist it's patriarchal archetype, if they have heard the phrasechoose your battles
- LocationGreater Chicagoland Area
- EducationUniversity of Wisconsin - Parkside
- WorkSoftware Developer at Stride Consulting
- Joined
I agree that history is importantbut 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.
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.
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
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.
- LocationPune, India
- WorkCo-founder and Director at Eloquent Studio Private Limited
- Joined
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
object.chained_medthod1.chained_medthod2.chained_medthod3object .chained_medthod1 .chained_medthod2 .chained_medthod3Elixir
object |> chained_medthod1() |> chained_medthod2() |> chained_medthod1()object |> chained_medthod1() |> chained_medthod2() |> chained_medthod1()I started learning Go a few months back, the language has first class support for this with thegofmt 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.
- Email
- LocationHouston, TX
- EducationB.S. Computer Engineering from Texas A&M University
- WorkMobile Architect at Credera
- Joined
unless it is a framework, module, class, method, variable names should be self documenting without need of additional documentation
Maybe I just don't understand what you mean here, but I would sayespecially in a framework you need to be careful with naming things and making code self-documenting. Frameworks just need documentationin 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 thewhy, not thewhat.
- LocationPune, India
- WorkCo-founder and Director at Eloquent Studio Private Limited
- Joined
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 foundthis one - another article about mistake on programming (its specific javascript on that article).
For further actions, you may consider blocking this person and/orreporting abuse
