5

I've considered making modules and the like for various languages and other open source things. Where documentation is not specified but rather is communal de facto standard or entirely ad hoc; should I try to improve from that standard in my code if it is not in-line with what I've learned to be good documentation from reputable sources (Code Complete et al)?

Or should I maintain consistency over all, regardless of quality?

Improve this question
1
  • 4
    But isn't this just like joining a new team? How would you expect to convey your ideas being the new guy without investing time and contributing initially in the already established way ? You do that first and slowly win em over.
    – Aditya P
    May 16, 2012 at 18:42

3 Answers 3

Reset to default
13

Consistency in a project is crucial both for the source code itself and the documentation. People who work on the project are habituated to use the standards they used for years, and would be lost in front of a piece of code or a part of a documentation which, in your opinion, is better, but which has nothing to do with the remaining codebase or documentation.

Also, be aware that it's not because you think that something is bad, it means that it is. Referring to Code complete doesn't change anything. What you may criticize might have its source in some elements related to the project, and while Code complete says it's bad, anyone who worked on the project for years would agree that in this specific case, it's the only choice.

If you want to improve the documentation of an existent open source project, gather some feedback from other people who participate to this project, and if you see that everyone agrees that the actual documentation is too bad, then well, you may want to rewrite it from scratch, following the best practices and keeping the consistency at the same time.

Improve this answer
12

Maintaining consistency is probably better to do initially, but I would contact the project owner(s) and ask whether you can suggest improvements to their documentation. If they agree, justify your suggestions and provide examples.

Improve this answer
3

"Bad" is in the eye of the beholder. Your "bad" may be their "beautiful". Until and unless you become a significant contributor, you should follow the established style.

Improve this answer
1
  • 1
    While he should follow the guidelines and most likely his commits will be rejected if he doesn't; Sometimes bad is bad on all accounts.
    – Andrew T Finnell
    May 16, 2012 at 22:32

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy