“I”, “We”, or Neither in code documentation

I find myself writing (hopefully) helpful comments in code (C++) documentation of the type:

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
<code>The reason we are doing this is...
</code>
<code>The reason we are doing this is... </code>
The reason we are doing this is...

The reason I use “we” instead of “I” is because I do a lot of academic writing where “we” is often preferred.

So here’s the question. Is there a good reason to prefer one over the other in documenting code:

  1. Use “We”: The reason we are doing this is…
  2. Use “I”: The reason I am doing this is…
  3. Use my name: The reason [my name] did this is…
  4. Passive voice: The reason this was done is…
  5. Neither: Do this because…

I choose #1 because I’m used to writing that way, but documentation is not for the writer, it’s for the reader, so I’m wondering if adding the developer name is helpful or if that just adds yet another thing that needs to be changed when maintaining the code.

8

I’d go with:

#6. Declarative:

Rather than say “The reason this was done is because each Foo must have a Bar”, just say “Each Foo must have a Bar”. Make the comment into an active statement of the reason, rather than a passive one. It’s generally a better writing style overall, better fits the nature of code (which does something), and the the reason this was done phrase adds no information whatsoever. It also avoids exactly the problem you’re encountering.

10

I prefer neither, and actually would leave off that introductory phrase altogether and just get to the point. I also try to avoid just saying “this” because it leaves no way to tell if the comment is in sync with the code. In other words, instead of:

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
<code>// The reason this was done is to prevent null pointer exceptions later on.
</code>
<code>// The reason this was done is to prevent null pointer exceptions later on. </code>
// The reason this was done is to prevent null pointer exceptions later on.

I would say:

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
<code>// Frobnicate the widget first so foo can never be null.
</code>
<code>// Frobnicate the widget first so foo can never be null. </code>
// Frobnicate the widget first so foo can never be null.

The fact you’re adding a comment at all implies you are stating a reason, so you don’t need to redundantly tell people you’re explaining the reason. Just make the reason as specific as possible, so they know as clearly as possible how to maintain that code later on.

In C# (and in most documentation tools in other languages) there is a difference between documentation and in-line commentary. My personal opinion is that you should always use formal, declarative-style comments as Bobson and others suggest in the documentation of a class or member, but within the code, there’s nothing wrong with being less formal. In fact, sometimes an informal comment is more effective at explaining why something is being don than a full exposition in formal English.

Here’s a sample which I think illustrates the point.

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
<code>/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
// Don't take candy from strangers
ComplexObject safeData = SanitizeData(data);
...
}
</code>
<code>/// <summary> /// Takes data from the remote client and stores it in the database. /// </summary> /// <param name="data">The data to store.</param> public void StoreData(ComplexObject data) { // Don't take candy from strangers ComplexObject safeData = SanitizeData(data); ... } </code>
/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

2

Another idea to consider would be a well crafted unit test that demonstrates why the code works the way it does in place of writing a descriptive comment. This has a couple benefits over writing comments:

  1. Comments do not always change when the code is changed which can lead to confusion later on.

  2. Units tests give the maintainer a easy way to play with the code. Learning a new codebase can be a lot easier if you have individual units that you can break to observe what changes.

Even though this avenue requires more work up front, unit testing can be an excellent form of documentation.

Good comments are hard to write, and even the best comments are often hard to read and comprehend. If your comment is concise enough for me to absorb and precise enough to convey what I need to know about the code, it doesn’t make me any difference what pronouns you use.

I would hate to discourage somebody from commenting their code because they’re concerned about the case, tense, and person of their pronouns.

1

The reason I use “we” instead of “I” is because I do a lot of academic writing where “we” is often preferred.

It is a bad style, even for academic papers, unless you are trying to hide who actually decided that exact point.

As for your specific question : I wouldn’t leave such comment, unless it starts with :

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
<code>// TODO: clean this up, ...
</code>
<code>// TODO: clean this up, ... </code>
// TODO: clean this up, ...

or unless it explains something very important, that might not be so clear from the code. In that case, make the comment as brief as possible.

Trang chủ Giới thiệu Sinh nhật bé trai Sinh nhật bé gái Tổ chức sự kiện Biểu diễn giải trí Dịch vụ khác Trang trí tiệc cưới Tổ chức khai trương Tư vấn dịch vụ Thư viện ảnh Tin tức - sự kiện Liên hệ Chú hề sinh nhật Trang trí YEAR END PARTY công ty Trang trí tất niên cuối năm Trang trí tất niên xu hướng mới nhất Trang trí sinh nhật bé trai Hải Đăng Trang trí sinh nhật bé Khánh Vân Trang trí sinh nhật Bích Ngân Trang trí sinh nhật bé Thanh Trang Thuê ông già Noel phát quà Biểu diễn xiếc khỉ Xiếc quay đĩa Dịch vụ tổ chức sự kiện 5 sao Thông tin về chúng tôi Dịch vụ sinh nhật bé trai Dịch vụ sinh nhật bé gái Sự kiện trọn gói Các tiết mục giải trí Dịch vụ bổ trợ Tiệc cưới sang trọng Dịch vụ khai trương Tư vấn tổ chức sự kiện Hình ảnh sự kiện Cập nhật tin tức Liên hệ ngay Thuê chú hề chuyên nghiệp Tiệc tất niên cho công ty Trang trí tiệc cuối năm Tiệc tất niên độc đáo Sinh nhật bé Hải Đăng Sinh nhật đáng yêu bé Khánh Vân Sinh nhật sang trọng Bích Ngân Tiệc sinh nhật bé Thanh Trang Dịch vụ ông già Noel Xiếc thú vui nhộn Biểu diễn xiếc quay đĩa Dịch vụ tổ chức tiệc uy tín Khám phá dịch vụ của chúng tôi Tiệc sinh nhật cho bé trai Trang trí tiệc cho bé gái Gói sự kiện chuyên nghiệp Chương trình giải trí hấp dẫn Dịch vụ hỗ trợ sự kiện Trang trí tiệc cưới đẹp Khởi đầu thành công với khai trương Chuyên gia tư vấn sự kiện Xem ảnh các sự kiện đẹp Tin mới về sự kiện Kết nối với đội ngũ chuyên gia Chú hề vui nhộn cho tiệc sinh nhật Ý tưởng tiệc cuối năm Tất niên độc đáo Trang trí tiệc hiện đại Tổ chức sinh nhật cho Hải Đăng Sinh nhật độc quyền Khánh Vân Phong cách tiệc Bích Ngân Trang trí tiệc bé Thanh Trang Thuê dịch vụ ông già Noel chuyên nghiệp Xem xiếc khỉ đặc sắc Xiếc quay đĩa thú vị
Trang chủ Giới thiệu Sinh nhật bé trai Sinh nhật bé gái Tổ chức sự kiện Biểu diễn giải trí Dịch vụ khác Trang trí tiệc cưới Tổ chức khai trương Tư vấn dịch vụ Thư viện ảnh Tin tức - sự kiện Liên hệ Chú hề sinh nhật Trang trí YEAR END PARTY công ty Trang trí tất niên cuối năm Trang trí tất niên xu hướng mới nhất Trang trí sinh nhật bé trai Hải Đăng Trang trí sinh nhật bé Khánh Vân Trang trí sinh nhật Bích Ngân Trang trí sinh nhật bé Thanh Trang Thuê ông già Noel phát quà Biểu diễn xiếc khỉ Xiếc quay đĩa
Thiết kế website Thiết kế website Thiết kế website Cách kháng tài khoản quảng cáo Mua bán Fanpage Facebook Dịch vụ SEO Tổ chức sinh nhật