“It turns out that style matters in programming for the same reason that it matters in writing. It makes for better reading.”
wrote Douglas Crockford, in Javascript: the Good Parts.
Doug wrote this over 10 years ago, perhaps when the IDE autocomplete and semantic completion wasn’t as robust. And definitely before TabNine (which smart writes code snippets for you).
Yet, even with our modern IDEs and decades of best practice, it seems we (newer) devs take to the 'shorter is a better' approach by claiming efficiency; this laziness comes at a cost to understanding your own code 2 weeks from now and someone else's code from two years ago.
So with some thanks to Doug for his tips and looking through public JS and Ruby repos, use these clear and concise coding styles practices do's and do-nots.
Single Line Statements
Use () and {} to spread your code over multiple lines.
Compact single line code is not the gold standard, readability and understanding are.
Specific (and Long Variable) Names
Don’t: let setWord = ""
Do: let UserAccountName = “ “
This is a real before and after renaming of the same variable example. Which one is clearer?
Don’t use the same name for multiple things.
On a React project, we initially wrote a Service component, a service state, and a service function. Yet each service had a unique task and we weren’t explicitly acknowledging this task.
A bit of refactoring cleared up our intent: keep Service for the model, rename the service state to serviceShowState, and the service function to showHideServiceCards().
With our powerful IDE’s, we can and should write long names. Otherwise, we don’t use the power and magic of the IDE!
Use adjectives AND verbs to give a sense of what variables hold - don’t use just nouns.
Specific (and Long) Function Names
Functions make things happen. Make it clear exactly what it does.
Don’t: updateState()
Do: updateStateForServices() assigned to an onClick callback showHideServiceCards.
Long names make you think about what your code is doing. Vague names could be said to be vague thinking.
Use adjectives AND verbs to give a sense of what functions do or return - don’t use nouns.
Explain Your Code - Use Comments
Earn that dev karama++.
In time you will move to a new project (or a new company) and experience the joys of using well-documented code. But only if you use clear, plain English on the code you left behind. Otherwise, dev karma-- for you
Group Functions and Files Together
Put your fetch requests in an API/Fetch file and/or folder.
Group event listeners, event handlers, and function calls with their brethren.
A skim of the code should let you and others know where things are.
Ruby loves convention over configuration. Apply such thinking to your own JS code.
Final thought, with a hat tip to @afteralec, *write code with the intention of others understanding your code. **
Have thoughts on writing style? Drop note. I'd love to hear and see your examples (or counterpoints).
Top comments (7)
Well naming conversions change from logic to logic .
So naming something as funcOnClick makes it clear that its an on click function emit but if I want to use the same logic somewhere else I am stuck with a very confusing naming of why in the hell is it names funcOnClick is a part of another function that is not triggered by the onClick.
So your solution is wrap functions with its dedicated expected behavior, very bad code IMO
Ryan, I concur with your thoughts. If the function (FuncOnClick, in your example), is used elsewhere and provides another behavior it should be renamed and/or refactored. What you are getting at is the need to think about what the function does across one's program and naming it appropriately.
The general idea of naming convention is that when I read your code I can assume what to expect the output of that function would be , (using interfaces is an extra bonus).
If you use a outside trigger to emit the function , the function should not care where its called from , as long as it gets the relevant arguments than it should all be fine.
Your suggestion could be relevant if there is some smart logic to do if the function is called from a click event and not from another place, so you can have a unique function from the click event (or pass it as an argument BTW - usually better ), Keep things as generic as possible is the key to go.
Fair point about being able to assume correctly what the expected output is of a function. When you say generic is the way to go, what do you mean by generic? The names, or something else?
It means not naming arguments (dataFromUserInput) => {...} and other examples can be added if needed.
simple is smooth, smooth is fast.
Making complex code is cool, but what happens if you want to change something, add something. how many places do you need to update your code in order to make your app not break, plus how many do you need to add to make the app show your change.
When you keep functions generic , i.e any one can use it and get the same result if they pass the same arguments , means many components of your code can use the same function for getting the information it wants, so changing only one function updates in a way in your entire application/server/whatever.
I went through your project and saw this line of code
Agreed. The example should be:
and it should simply be assigned to the
onClickcallback of the UI.Yes. I updated the example. Thanks for helping clarify . :)