Hacker News Reader

Comment by lwhi | Hacker News Reader

How we name things matters.

If we want to be communicate effectively, it's important to think carefully about the words we use.

Writing code serves two purposes. On one hand we're instructing a machine to carry out the operations needed to achieve our aim; but on the other, we're helping our peers understand how we got there.

There usually aren't many technical restrictions in place when naming things in code; we have a lot of freedom. Based on this freedom, I think guidance, strategy and discussion re. establishing conventions would definitely be useful.

View on HN

I agree, and I suppose a lot of it is communication 101. Part of that is knowing your audience. You'd need to ask yourself a bunch of questions ("and you want to have them answered immediately!!").

* Who is your audience?

* Who do you want to be your audience?

* Are they technical or not?

* Are they familiar with the content?

* Are they native English speakers?

* Will non-native English speakers understand the communication?

I'm by no means an expert on this subject, so I'm unsure this list is complete.

I think these are all good points when it comes to writing technical documentation, but with naming things in code there are a different set of problems.

You can't hone your approach for a specific type of audience, because you can't make assumptions about who'll be reading it.

I think we can assume they're technical, and that they're proficient in the language the code is written in. Maybe we can't really assume they're familiar with the project, they could be new to it; but I think it's fair to say they're willing to be invested enough to become familiar.

The way we name 'things' in code, allows the reader to infer more about that 'things' place, contextually, within a larger structure.

* How can I indicate what this structure contains?

* How can I show why I have chosen this approach?

* How can I show how this section of code relates to the larger code base?

* Does this 'thing' relate to a larger structure?

My default audience is myself before I started working on this problem. I assume general and technical knowledge, but little domain-specific knowledge and no knowledge of how the solution works.

Sometimes I'll target specific team members whose knowledge doesn't overlap mine well. Or I'll drop URLs for background info in block comments.

Reply on news.ycombinator.com