DEV Community

Code for Humans

Deepak Singh on June 22, 2018

white-spaces are code too... It's great, your code works in production and is fast enough. Congratulation, but... Is it readable enoug...

Read full post

anabella • Jun 22 '18

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.

Deepak Singh • Jun 23 '18

Thanks Anabell-o, I have made the change.

MetaDave 🇪🇺 • Jun 23 '18

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

Daniel • Jun 23 '18

Try using "resources", instead.

MetaDave 🇪🇺 • Jun 23 '18

Bit impersonal for me

Jason Gade • Jun 23 '18

And "employment units" isn't?

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

anabella • Jun 22 '18

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

TMcSquared • Jun 22 '18 • 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

anabella • Jun 23 '18

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.

John Alcher • Jun 23 '18

~~Guys~~ People get triggered with anything these days lmao.

MN Mark • Jun 22 '18

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.

Deepak Singh • Jun 23 '18

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.

MN Mark • Jun 23 '18

Fully agree

Kyle Stephens • Jun 22 '18 • 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

Sean • Jun 23 '18

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

Stevie Oberg • Jun 23 '18

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.

Daniel • Jun 23 '18 • 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.

Casey Brooks • Jun 22 '18

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.

Deepak Singh • Jun 23 '18

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