(Better) English for web developers

Everyone knows there’re two hard things about programming, and one of them is naming things. This problem doesn’t get easier when a developer is of a non-english-speaking-descent. Naming gets very approximate, and every new team member adds a new layer to this approximation. Result: a codebase falling appart just because a coder is not a born Hemingway. Sad.

well, that’s life man

How could we change this and come a few steps closer to efficient technical communication? I’d suggest splitting the answer into several important blocks ranged from less global to extremely so.

Some of these recommendations are pretty obvious, but often neglected, so please don’t discard them with a whiff! Many codebases would get so much prettier if only we all followed those intuitive steps (me included!)

Yes, we do!

Better naming (= for shorter texts)

• Describe what The Thing does in detail. It’s fine if it is longer than you expected. E.g., set_restrictions_for_non_admin_users is more specific than just `set_restrictions`, so easier to use properly.
• However, if your precise description is getting out of hand and spans over a whole paragraph, don’t push too far. If The Thing is so hard to describe, maybe split it into several things that are easier to name? For instance, instead of having a bleak manage_order that is too generic you might have `check_availability`, checkout, `send_report` and `recalculate_stock`. In certain cases `manage_order` would be fine, though — depending on how granular you need to be.
• Avoid information that is only meaningful in the current context. Generally speaking, if you are tempted to use words like improved , `better`, or `fixed`, please reconsider your naming choice. Similarly, `new_tracking_options`, optimized_record_count, or another_way_of_something are NOT valid options!)
• I can’t emphasize the power of googling enough! It’s definitely a good idea to Google-translate your suggested naming both forward and back into your language — you might learn that a cool-sounding phrase means something quite different. Also, check what results a search query with your method name returns. If could give you some inspiration and provide with common collocations to use in your context. Contrary to your usual googling with just importance-range keywords, here it’s actually useful to search for your exact phrase: what context does it usually appear in? Does it exist? Is it the proper verb or preposition? These are really important questions!
• There’re services that check your grammar and spelling! Some of them are paid, others have a free version (Grammarly is an amazing tool, and it also works for short phrases).
• Internal conventions are a great help when you want to structure your codebase. Think about `?` at the end of a method that returns a boolean, or `call` vs `execute` vs `run` when you have a service to launch, or using an accepted structure for a method name (like: what it does, in which context, for what type of user, what it returns). Don’t keep these conventions to yourself, suggest them to your team and document those you judge worthy.
• Probably a detail, but still: in most cases in headers and titles (such as a method name!) don’t require articles, so feel free to omit them.
• Discuss the naming with the colleagues but remember: the fact that some of them would rather use a bad translation from their mother tongue than a proper wording doesn’t make it a valid option. Use these discussion as a way to improve the team’s linguistic skills and not to justify bad choices!
• Don’t hesitate to check for naming mishaps in your team’s pull requests. It’s as good a comment as spotting a syntax error or an suboptimal SQL query!

Better pull requests and pull request comments (= for longer texts)

• Many people have trouble with using a full stop. Don’t fall into this trap! Shorten your phrases! You honestly don’t need extra adjectives or adverbs in your PR comments. Most commas don’t have to be there, either. If there’s no full stop followed by a capital letter on each line, you should definitely use some.
• Split the important blocks, paragraph-less texts are much harder to read.
• Follow my lead, use bullet lists with only the essential information in the subject. Brief and clear, just highlight what needs to be done: `missing argument X` or `optimize this query like this`
• Verbally separate what must be done in your opinion and what is nice to have. Sometimes from a reviewer’s comment you can’t tell if you should stop whatever it is that you’re doing and make the requested changes or of they are nice-to-have extras. So, it would definitely help if you add “let’s try” or “maybe” or “I would do it this way”, together with important! and `To Do` tags.
• If you still doubt if your message is clear, don’t hesitate to illustrate your idea with a bit of code.

how hard can it be to find a better picture?:(

If these little tips make your codebase great again (oops, a dubious collocation detected!), I’d be really glad. And if you have more ideas on how to improve developers’ English writing, please share! Let’s make this problem disappear.