Comments & OpenSource software [closed]

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 7 years ago.

Improve this question

This may sound like a foolish question or an observation, but i have seen that most of the times when one tries to look at the opensource code, there are no comments or just one or two lines at the start of the function telling what the function is used for e.g. register 开发者_JAVA技巧a user or data in table etc. There is no code which actually explains what exactly the function is doing etc.

Is it done intentionally (removal of comments) when a code is released to open source community to make things difficult to understand by others?

---

There is a line of thought that says that comments are unnecessary when the code speaks for itself. I don't believe comments would be removed on purpose, though.

---

I've seen both sides, and frankly code in general is insufficiently documented.

I've been congratulated and thanked for leaving copious breadcrumbs but that's because I've had to sift through too much undocumented code to want to subject anyone else to it.

Call it an ethical obligation.

My reason to document code: my short-term memory is junk. I write comments to remind myself of why I did something. Everyone else benefiting from that is gravy.

---

I don't think there is a practice or policy to remove comments when releasing software as Open Source. A sneaky software publisher might think that a good idea (maintaining de facto exclusivity, because nobody can't understand it, while having released an open source product) but this would cripple the Open Source project from the start and most likely render it unusable.

The code you are talking about is probably just very little documented. As ocdecio says, that can be either a good sign (the code speaks for itself and does not need comments) or a bad one (it is badly documented, bad code). Both cases are entirely possible. :)

---

What are you comparing it to?

I doubt that closed-source code has better comments.

As for what functions do, there is probably API documentation. No need to duplicate those in comments.

---

As a rule, functions should be small enough and written in a way that allows working out how it works by just reading them. A comment on top of the function describing what it does helps getting a quick overview of the function itself when reading through the whole source code file (unless the function name speaks for itself).

Many projects are organized in that way, and that is great.

However, what I am often missing when trying find my way around a larger codebase is something describing the big picture, i.e. the general architecture, principles, what goes where and similar things.

---

All open source is not made the same. This is what we call a generalization.

If you look at the website Ohloh, which tracks a very large amount of the open source software in existence, it paints a much different picture:

http://www.ohloh.net/languages?query=&sort=code

For instance, in the C language, there are 252+ million lines of comments, approx 1 in every 5 lines of C is a comment. For Java, nearly 1 in 3 lines is a comment. That's not bad.

---

Open source software has bad comments and bad documentation most of the time. There are various reasons why, some better than others. Usually they relate to laziness or the developers 'being in the moment'. None of the reasons are good reasons.