1

What is the difference between these two phrasings? I came across them in Effective Scala. I'm adding the whole paragraph to provide some context:

Document APIs but do not add unnecessary comments. If you find yourself adding comments to explain the behavior of your code, ask first if it can be restructured so that it becomes obvious what it does. Prefer “obviously it works” to “it works, obviously” (with apologies to Hoare).

1 Answer 1

2

Actually, they mean the same. Or, they mean the same, actually. ;)

Although they mean the same, there is arguably a little difference in inference to the ears of a native speaker. What you say first comes over as your statement, and what comes second as your supporting statement.

In most contexts, saying "obviously it works" does sound a little arrogant. It sounds like you are sure it works before testing that statement. That isn't what it means, but that is how it sounds. Saying "it works, obviously" does not sound quite so arrogant - it sounds more like you are sure it works, and are adding "obviously" to show that fact is apparent.

In the context of your example, it seems that the writer prefers "obviously it works" to the alternative. Context is everything, and if that is what they feel is most respectful in comments by developers on code, then that is the agreed protocol in that particular setting.

2
  • Your answer makes sense, but unfortunately I still don't understand what they meant by it.
    – Adam
    Commented Feb 25, 2020 at 11:58
  • The entire instruction means that, when developers write comments on code, they don't want unnecessary comments, and they express a preference for one phraseology over the other. Their preference is actually the opposite of what I said, but context is everything. I've updated my answer a bit.
    – Astralbee
    Commented Feb 25, 2020 at 12:05

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .