English 中文(简体)
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.

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 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.





相关问题
VS 10 mangles html comments?

Using the latest VS 10 we created html markup, then commented it with html comments. The file on disk is not mangled, but when it renders, it renders the html comment tags, then removes some of the ...

Comments & OpenSource software [closed]

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 ...

Including commented Class declaration in implementation file

Everyone knows the advantages of a more readable code. So in order to make my code more readable what i do normally is include the commented class declaration in the implementation file of that class....

pair programming with comments [closed]

Over the years, I ve discovered that green-programmers tend to read the comments rather than the code to debug issues. Does having one person document the other person s code (and vice-versa) with ...

Commenting JavaScript functions á la Python Docstrings

It is valid JavaScript to write something like this: function example(x) { "Here is a short doc what I do."; // code of the function } The string actually does nothing. Is there any reason, ...

热门标签