DEV Community

loading...
Cover image for Code for Humans

Code for Humans

spidergears profile image Deepak Singh ・2 min read
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

    Discussion (23)

    pic
    Editor guide
    Collapse
    anabella profile image
    anabella

    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.

    Collapse
    spidergears profile image
    Deepak Singh Author

    Thanks Anabell-o, I have made the change.

    Collapse
    rolypolie profile image
    Sky

    "guys" is a general term that's been around for ages to describe a general audience ..if he had said "men" then that would be a different story.. I'm ok with guys.

    Collapse
    databasesponge profile image
    MetaDave 🇪🇺

    I use the term "employment units", and nobody has complained.

    Thread Thread
    6temes profile image
    Daniel

    Try using "resources", instead.

    Thread Thread
    databasesponge profile image
    MetaDave 🇪🇺

    Bit impersonal for me

    Thread Thread
    tinsoldier6 profile image
    Jason Gade

    And "employment units" isn't?

    Oh, wait. That's the joke, right? 😊

    Collapse
    alchermd profile image
    John Alcher

    Guys People get triggered with anything these days lmao.

    Collapse
    insuusvenerati profile image
    Sean

    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

    Thread Thread
    stevieoberg profile image
    Stevie Oberg

    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.

    Collapse
    moopet profile image
    Collapse
    anabella profile image
    anabella

    Me too. "guys" is still my go to expression to address a group. But by caring we can change. Thank you! :D

    Thread Thread
    tmcsquared profile image
    TMcSquared • Edited

    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

    Thread Thread
    anabella profile image
    anabella

    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.

    Collapse
    mjb2kmn profile image
    MN Mark

    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.

    Collapse
    spidergears profile image
    Deepak Singh Author

    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_medthod3
    
    object
      .chained_medthod1
      .chained_medthod2
      .chained_medthod3
    

    Elixir

    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 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.

    Collapse
    mjb2kmn profile image
    MN Mark

    Fully agree

    Collapse
    ky1e_s profile image
    Kyle Stephens • Edited

    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

    Collapse
    6temes profile image
    Daniel • Edited

    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.

    Collapse
    cjbrooks12 profile image
    Casey Brooks

    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 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.

    Collapse
    spidergears profile image
    Deepak Singh Author

    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 :)

    Collapse
    khanhtc1202 profile image
    Khanh Tran

    Very nice article! Moreover, I found this one - another article about mistake on programming (its specific javascript on that article).