63

I work in a small development company which has an open and friendly atmosphere, and am the most junior employee. We have a cloud-based repository for user documentation, private documents such as server specifications and developer deployment guides. Many of these are written with haste or aren't proof read, and often when I read through the documents for my work tasks I come across simple spelling mistakes, typos and incorrect grammar. In other instances, in the code I come across many typos in debug statements, console output and messages that are presented to the user.

Would it be considered bad etiquette, or petty if:

  • I edited these documents to fix grammar and spelling, especially on the documents which aren't public-facing?
  • The original author is dyslexic?
  • I were to commit fixes to spelling and grammar mistakes in code, and make no changes to the actual functionality of the code?
  • Comments are not for extended discussion; this conversation has been moved to chat. – Lilienthal Aug 9 '17 at 21:11
  • 24
    I'll just leave this here: en.wikipedia.org/wiki/HTTP_referer – Monty Harder Aug 9 '17 at 22:02
  • One caveat is that as the newest employee you may not know things that could save you from making embarrassing mistakes. For example, what if I fixed your post to use Oxford commas (which you clearly don't like)? Although there is a plausible correctness in my doing so, perhaps to you it's wrong because you use a different style guide. Proceed slowly (though I support improving these things, strongly—see my pending edit to your question, though I had to edit more than I wanted, mostly I wanted to fix the spelling of "proof read" to "proofread"). – CodeSeeker Aug 10 '17 at 19:49
  • @Donglecow - are you working on the areas of code you want to change? Are the grammar and spelling mistakes in the variable and method names? – Luke Aug 10 '17 at 22:52
  • 2
    Speaking as non-native speaker: while I do my best effort to write correctly some errors are inevitable. I hope most issues will be corrected during review. If I were you I would just bundle all changes as one thing, separate from code changes, for review but that depends on company culture. I would feel hurt though if anyone but me commented my knowledge of English - I would assume the dylexic person wouldn't like to have their disability commented upon as well - so I wouldn't draw attention to it and keep it as impersonal as possible (no reason to mention why the mistake is there). – Maciej Piechotka Aug 11 '17 at 0:20

11 Answers 11

98

I were to commit fixes to spelling and grammar mistakes in code, and make no changes to the actual functionality of the code?

Tread carefully here.

Often, any code changes have down-stream effects. A code review might be required. Testing might be required. A security review might be required. Etc. Changing spelling and grammar mistakes might trigger a lot of unscheduled work from others.

And while your intent is to make no changes to the actual functionality, bugs happen.

Before you change any code - ask.

Would it be considered bad etiquette, or petty if:

  • I edited these documents to fix grammar and spelling, especially on the documents which aren't public-facing?
  • The original author is dyslexic?

That depends mostly on the culture of your organization.

In some companies, continuous change by everyone who reads such documents is welcome. In other companies, it would be considered rude without the author's permission.

  • Comments are not for extended discussion; this conversation has been moved to chat. – enderland Aug 15 '17 at 15:40
56

I consider this kind of change an improvement in quality. Internal documentation has a value although it's not facing end-user, and improving the quality of it makes it more valuable. I also personally tend to trust documentation more if it doesn't have a huge amount of typos in it. Sometimes a typo or wrong grammar might also change the meaning or lead to misunderstandings.

To summarize it: I find it rather positive.

Be careful though that if you happen to spend a lot of time doing that, people might wonder if you don't have anything better to do, like coding...

  • 33
    I often do this while developing that part of the code. You know, "leave the place in better condition than you found it in" and all... – Juha Untinen Aug 8 '17 at 15:18
  • 3
    I remember that Sun had to go through a lot of comment clean-up when all the typos became a public embarassment (due to their exposure via javadoc). – Peter A. Schneider Aug 9 '17 at 14:44
  • With regards to your last sentence, isn't there an argument to be made for code being read more than it is written (or something like that)? – seth10 Sep 22 '17 at 21:03
  • 1
    @setht well commented and/or self-commenting code is one thing, documentation is another thing. I would expect a dev to spend more than half of his time coding than proof-reading documentation... – Laurent S. Sep 23 '17 at 20:06
14

Assume the worst of your changes:

  • You make mistakes that breaks something
  • Your relatively minor commits might clutter changelogs etc
  • Your employer might think your time is spent doing more useful things

Due to this, I only make "unsolicited" changes if, basically, I was changing the code/document anyway. So if I'm being tasked changing some class, and I know that its functionality will have to be re-tested anyway, I might as well also refactor it and fix some spelling it if I genuinely believe it will improve quality or save everyone time in the end. As other answer mentioned: the "boy scout rule" - leave the camp site more tidy than they were when you got there.

But, don't accidentally start bush fires by camping unnecessarily :) For any other changes, make a case of it to whoever is deciding what you do. Explain benefits of the fixes, and any risks. Examples of benefits could be that misspelled code inhibits searching the code base, negative user perception from misspelled messages or documents, etc. Let them decide whether its worth the time/risk.

  • I find your guideline very appropriate (and missing in the other answers, if I see correctly): Make unsolicited changes of a cosmetic kind only when you touch that file anyway. (And make it two distinct commits, many would add.) – Peter A. Schneider Aug 9 '17 at 15:54
  • I complete agree. I was in the same boat as OP in the past and I settled into fixing cosmetic issues as I push bug fixes for those modules... I waited like six months to fix a glaring typo (a local function named get_locgat_file(), referring to android's logcat) until there was a bug-fix to be committed. – TemporalWolf Aug 9 '17 at 19:44
  • 1
    "I only make "unsolicited" changes if, basically, I was changing the code/document anyway." -- +1, related term: "boy scout rule" or "Always leave the campground cleaner than you found it" – Kos Aug 10 '17 at 10:46
4

I were to commit fixes to spelling and grammar mistakes in code, and make no changes to the actual functionality of the code?

Are there any mistake visible for the public (in front-end) or the client (at client's console log)?

If yes, ask the team/project leader about authorizing you to correct them.

If no, do nothing or ask the team/project leader if you can do some refactor and fix then with any other issues the code could have.

In any case, don't criticize your coworker, specially if he's dyslexic.

4

If we are talking really minor changes such as fixing typos or missing commas etc. then I wouldn't say it's a bad thing to just fix them as you find them. What I wouldn't do is go around telling anyone you've made the changes as that might seem like attention-seeking at best and being a petty spelling/grammar-nazi at worst.

Another advantage to fix-as-you-find is that you don't want to come off as someone who is hunting for these mistakes.

Code can be a little different - although you do state that you aren't changing actual code so I'm assuming it is just things like comments so there is zero possiblity of it impacting on functionality in which case I'd suggest that's fine.

3

Do not change code unless it is tied directly to the bug or enhancement ticket you are working on. (you do have a ticketing system of some sort for work on existing systems, right?) Your change should also be necessary to complete the work of the ticket.

If you firmly believe that this code should be changed, create a ticket for review and if approved, you can do the work.

As the saying goes, "No good deed goes unpunished". There are so many ways that what seems like a trivial edit could go wrong, sometimes in a delayed fashion.

For example, at my company we have built an alert system based on monitoring/scraping log files. Error messages in logs can generate anything from a minor warning to an all hands alert. Over the years, we have unfortunately created log error messages with all variation of typos. If some over-zealous developer "fixed" the error messages, our alerting system might suddenly go silent.

  • Sounds like you need to submit a ticket to fix your alert system, as that's a powder keg waiting to go. – TemporalWolf Aug 9 '17 at 19:44
  • Alert system works fine. If you want granular alerting, you need specific trace in the logs to check for. Works fine as long as people don't make uninformed changes. – cdkMoose Aug 9 '17 at 20:44
  • The answer seems to have nothing to do with the question. The OP is asking about fixing comments and shared documents. – AnoE Aug 9 '17 at 20:49
  • @AnoE, the third bullet specifies code, not comments. The paragraph includes " debug statements, console output and messages that are presented to the user." Clearly this is real code and not comments or documentation. – cdkMoose Aug 9 '17 at 21:16
  • Well... I thought it was the point of this question that he is asking about the non-functional parts of the code (i.e., not output including in a logfile). But you are right insofar as some parts of the question make it questionable whether that was the intention. – AnoE Aug 9 '17 at 21:56
3

What this really boils down to is the context.

For instance, I work for a multi-national company on a team that is located across multiple countries. I'm the sole native English speaker, so I encounter grammar and spelling mistakes in our code names and comments on a daily basis.

I typically leave them as are, as correcting the mistakes yields no benefit, and it is always very easy to understand the intention of the writer due to the context. (Off the top of my head, I can think of a folder accessed by several files with the name "ressources".

Changing names can have waterfall effects if it's an actual code object, and if the name is descriptive albeit misspelled, I don't see the benefit to adding to your own workload.

I don't believe my foreign coworkers would be offended if I started correcting their errors in my commits, but over time, if I were to do it over and over and over again, they may start to feel like I think their English skills are inadequate.

Bottom line, ask yourself if the context of the situation is worth the extra work and if the context means a potential slight against the original author.

I don't believe that correcting spelling and grammar mistakes in other's code will give anyone the impression that you're a better coder for it, only that you have a better grasp on the English language.

2

Public facing documents and log entries should have much higher standard in terms of spelling and grammar correctness than internal documents and code. Of course, it is advisable as well to constantly clean up the code you are working on. This means that whenever you are working on a feature/bugfix, you should leave the affected part cleaner than it was before (boyscout rule). What should not be the case is that when you edit the code, the changes contain only fixes of grammar and spelling.

Also, you should ask your manager before doing this habit regularly, because he/she can help you in approaching your colleagues that could be sensitive towards correcting their contributions.

  • While I agree (and this is applicable here) the line may be blurred. Especially in software development quite some documentation (for public consumption possibly) is auto generated from internal comments ;) – TomTom Aug 8 '17 at 15:03
1

There are two categories you are dealing with here: public facing documents and internal documents and code.

For internal documents and code, don't bother with superfluous changes. As long as the files are understandable and work as they should, then there's not really anything to be gained. Edits like this don't really add anything and can clutter up your version control history. However, if you are already making a change to a particular document and see some typos to fix too, then go ahead. In that case it's really more of an add-on to an already necessary change.

For public facing documents and UI messages, it is important to make sure there are few errors and everything is grammatically correct. If it's something that is clearly incorrect, then I would certainly change it. If it is a more subjective change (e.g. changing wording, or the Oxford comma), then I would consult with the primary author or your manager before saving any edits. Again, I find a lot of small edits like this can clutter up version control, so I personally prefer to save the changes with other more important updates or to set aside the edits and do a batch upload of a bunch of copy-edits at once. That's something you can talk to your manager about to see what they prefer.

  • 7
    I disagree with combining cosmetic (spelling/grammar/formatting/etc) and functional changes into a single commit, clutter in a commit is worse than the change log. I prefer to keep them separate; that way if I'm blaming the code to find out why something is the way it is I can look at the commit comment and (eg "spelling fix" vs "Issue-12345 Fixed reticulation of splines on Tuesday afternoons if using Windows 8") and immediately know I need to look at the previous version vs potentially thinking that the line in question was created/edited as part of the commit that incidentally fixed a typo. – Dan Neely Aug 8 '17 at 19:57
1

I work in a small development company which has an open and friendly atmosphere, and am the most junior employee.

You have a manager. That is the person you should be asking !

Our opinions can be looked on as advice, but your boss is the person who must make a decision. They must decide how your time is best used.

I come across simple spelling mistakes, typos and incorrect grammar.

If you are authorized to change these documents and certain you are not changing the intended meaning, then I presume it's OK. However, being certain of the intended meaning is non-trivial and it's easy to alter the meaning without intending to.

In other instances, in the code I come across many typos in debug statements, console output and messages that are presented to the user.

Errors in code (messages of any kind included) need to be properly addressed using a bug tracking system. They can then be prioritized properly and dealt with on that basis.

And it's possible to screw up these changes and mess up code doing it. Happens all the time.

Would it be considered bad etiquette, or petty if:

I edited these documents to fix grammar and spelling, especially on the documents which aren't public-facing?

Private internal documents do not particularly need to be fixed in this way. Prioritize other work over this.

The original author is dyslexic ?

The original author's capabilities or limitations are not relevant to how your time is used.

I were to commit fixes to spelling and grammar mistakes in code, and make no changes to the actual functionality of the code?

Any change to code is a formal change. Changes to comments and other elements can introduce bugs - people make mistakes doing this. I advise against this without explicit instruction from your line management.

0

If the document isn't public-facing, as you mentioned for some of them, then what is the actual benefit to making these corrections, other than it not bothering you?

If you're not changing the functionality of the code, and the improved grammatical presentation does not impact the company's image, at all, then you have added no value to the code.

If you spend time "fixing" something that adds no value, you have just wasted your own time and your employer's time and money, which is not the way to go for anyone, but especially the most junior person in the food chain.

You're likely to irritate people, who will ask "why did this need fixing?", and you're likely to raise the general question - "Doesn't this person have value-adding work to do? If not, is this person's job necessary for us to have, at all?"

Do not even ask if it's okay to make these fixes, because there is no problem to fix, and no improvement offered by making the fix.

For messages that do get presented to end-users/customers, definitely ID them for fixing, let someone higher up know that you saw it, and offer to correct it. Certainly, basic errors of that sort do not reflect well on the company, so fixing those does add substantial value.

  • The benefit is that spelling mistakes and grammar errors make a document harder to read. Improving the readability of internal documents is good. – Martin Bonner Aug 9 '17 at 7:23
  • @MartinBonner - OP describes them as "simple spelling mistakes, typos and incorrect grammar" - and understands them well enough to be able to make the corrections, so, clearly they are not hard to read, at all. If I tipe this sentance instead of the more correct "type this sentence," no one is going to have an epiphany based on changing an "i" to a "y" and an "a" to an "e". OP is not talking about gibberish, just cleaning up what is completely understandable to start with. I would take the care to get it right, or to correct my own work if I saw it. I don't see the value of this undertaking. – PoloHoleSet Aug 9 '17 at 14:07
  • 1
    I wasn't talking about "having an epiphany", I was talking about how quickly I can read it. "If I tipe this sentance" is understandable - but it takes more effort to do so. Reducing that effort is worthwhile. – Martin Bonner Aug 9 '17 at 14:46
  • @MartinBonner - If you deem that to require "effort," then we'll have to agree to disagree, I guess. – PoloHoleSet Aug 9 '17 at 14:58
  • This is the answer I came here to give. You shouldn't spend your time fixing grammar/spelling issues in non-user-facing docs. I've done this before. I felt productive at the time but honestly I should have been working on the product instead. A good guideline is to only invest time in fixing things like this if the document is unusable as-is or you are already touching that file doing product or refactoring. – chucksmash Aug 10 '17 at 15:06

protected by Lilienthal Aug 8 '17 at 14:59

Thank you for your interest in this question. Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.