| robertshield | 58e0b3f | 2017-02-14 03:55:39 | [diff] [blame] | 1 | # **Chromium Documentation Guidelines** |
| 2 | |
| 3 | Chromium's code base is large. Very large. Like most large places, it can be hard to find your way around if you don't already know the way.It also changes a lot.Lots of people work onChromiumand refactoring, componentization, addition |
| Nourhan Hasan | 571a2f2 | 2024-07-26 16:50:48 | [diff] [blame] | 4 | or removal of layers, etc. means that knowledge one has can quicklygetout of date. |
| robertshield | 58e0b3f | 2017-02-14 03:55:39 | [diff] [blame] | 5 | |
| 6 | As a result, it can be hard to figureout how things are supposed to fit together.Documentation on[dev.chromium.org](http://dev.chromium.org/developers) can be hard to navigate and harder to keep up to date. The [starter guide](https://sites.google.com/a/chromium.org/dev/developers/how-tos/getting-around-the-chrome-source-code) is helpful, but stops at a very high-level overview. Ultimately [codesearch.chromium.org](http://codesearch.chromium.org) is the way most people explore. |
| 7 | |
| 8 | This guide attempts to layout some practices that will make it easierfor newcomers to find their way aroundChromium's code and for old hands to keep up with a constantly evolving code base. It works from the principle that all documentation is wrong and out of date, but in-code documentation is less so and valuable. |
| 9 | |
| 10 | ## Guidelines |
| 11 | |
| 12 | In-code documentation can be categorized into three tiers: |
| 13 | |
| 14 | * **Module / component documentation**: This is documentation that tends to be found in README.md files at the root level directory of a component. The purpose of this type of documentation is to explain what a given set of related classes are for, roughly how they are structured and *what* the component is expected to be used for. |
| 15 | * **Interface / class documentation**: This is documentation most often found in header files near class definitions. This may describe what a class or small set of classes are for and *how* they are intended to be used. It may also provide examples of usage of the class where this isn't obvious. |
| 16 | ***Implementation documentation**:This type of documentationis foundnext to implementations.In C++,this will tend to be embeddedin.cc files.Itis meant to help a reader understand*how the code works*or explain an implementation path that mightnot be obviousfrom the code itself. |
| 17 | |
| 18 | Let's dig in a bit to how to use these types of documentation in Chromium. |
| 19 | |
| 20 | ### Module / component documentation |
| 21 | |
| 22 | Ok, so you're working on something bigand important.Maybe it's a chunk of code that merits living in its own component in [src/components/](https://codesearch.chromium.org/chromium/src/components/) or even directly under [src/](https://codesearch.chromium.org/chromium/src/) itself. One day someone's going to come alongand wonder what it's for and they'll discover that awesome-directory-name(breakpad, courgette, mojo, rutabaga, quick: which one of those was made up?) doesn't by itself shed a lot of light on what the code does. |
| 23 | |
| 24 | ***Any self contained unit of code that merits a container directory should have a README.md file that describes what that component is, how it is expected to be used and provides rough outline of the code's structure.*** |
| 25 | |
| Mike Frysinger | d1630aa | 2024-07-11 01:41:24 | [diff] [blame] | 26 | The README.md file should be located at the root of the component directoryand should bein[markdown format](/styleguide/markdown/markdown.md). |
| robertshield | 58e0b3f | 2017-02-14 03:55:39 | [diff] [blame] | 27 | |
| 28 | The first thingin the README.md file should be a description of the componentin sufficient detail that someone unfamiliarwith the code will understand why it exists.It should answer the questions"what does this component do?"and"is there any in particular I should know about it?".Some larger components(e.g. v8, mojo, etc.) may have additional up-to-date documentation on[dev.chromium.org](http://dev.chromium.org) or elsewhere makes sense too. |
| 29 | |
| 30 | The second thingin the README.md file should be an outline of how itis expected to be used.For components of small to moderate size(e.g. under[src/components/](https://codesearch.chromium.org/chromium/src/components/)), this can mean what are the main classes to care about. For larger components this can describe how to go about using the component, possibly in the form of links to external documentation (e.g.: [src/v8/](https://codesearch.chromium.org/chromium/src/v8/README.md)). |
| 31 | |
| 32 | The third thing should be a lay of the land of the component, sufficient breadcrumbsfor a newcomer to be able to orient themselves.This usually means at least an explanation of the subdirectories of the componentand possibly a description of the major interfaces a consumer of the component will need to care about.Againfor larger componentsthis can livein external kept-up-to-date documentationwhere needed. |
| 33 | |
| 34 | The fourth thing should be historical links to design docsfor the component, including early ones.These aresuper handyfor people looking to understand why the component existsin its current form. |
| 35 | |
| 36 | A great example of a README.md fileis[src/native_client/README.md](https://codesearch.chromium.org/chromium/src/native_client/README.md). There are many more examples that are waiting to be made great. |
| 37 | |
| 38 | ### Interface / class documentation |
| 39 | |
| 40 | Classandfunction declarationsin header files describe to the world how a piece of code should be used.Thepublicinterface of aclassor a header file containingfunction declarations describe the API to the code but don't necessarily say much about how it is expected to be used. As such: |
| 41 | |
| Nourhan Hasan | 571a2f2 | 2024-07-26 16:50:48 | [diff] [blame] | 42 | ***Non-trivial classes or sets of function declarations in header files should include comments with a brief description of the purpose of the class or set of functions as well as examples of expected usage.*** |
| robertshield | 58e0b3f | 2017-02-14 03:55:39 | [diff] [blame] | 43 | |
| 44 | (Good) examples: |
| 45 | |
| 46 | https://codesearch.chromium.org/chromium/src/base/callback_list.h |
| 47 | |
| 48 | https://codesearch.chromium.org/chromium/src/base/feature_list.h |
| 49 | |
| 50 | ### Implementation documentation |
| 51 | |
| 52 | Code should be as self documenting as possible, but sometimes that isn't enough.Maybe there's a tricky bit of implementation that isn't obvious.Maybe there's a clever algorithm that has a good reason it needs to be clever. A good rule of thumb is that if a code reviewer had a clarifying question about something during review and the code couldn't be simplified to answer the questionthen a commentis probably appropriate.Don't go nuts here though, often if code is so complicated that it needs lots of comments, then it could probably be simplified first. |
| 53 | |
| 54 | ## Language |
| 55 | |
| 56 | Be concise. |
| 57 | |
| 58 | Use correct grammar as much as possible. |
| 59 | |
| 60 | Avoid fancy or confusing language. |
| 61 | |
| 62 | Don't assume that readers know everything you currently know. |
| 63 | |
| 64 | ## Working with existing code |
| 65 | |
| 66 | If you gotthis farand have some experiencewithChromium's code, you'll have figuredout that these guidelines are aspirational more than what the world looks like today.So whatdo wedowhen workingwith existing code. |
| 67 | |
| John Palmer | 046f987 | 2021-05-24 01:24:56 | [diff] [blame] | 68 | First off:***[Documentation changes can beTBRed](https://chromium.googlesource.com/chromium/src/+/main/docs/code_reviews.md#documentation-updates)***. Even in-code changes. If you have discovered something that isn't documented, have figured out how it works and would like to pay it forward, feel free to write something down and check it in. |
| robertshield | 58e0b3f | 2017-02-14 03:55:39 | [diff] [blame] | 69 | |
| 70 | At the component level,if you are the owner of a component that isn't documented, please add a README.md with content as per the above. |
| 71 | |
| 72 | If you don't own a componentand figureout how it works, consider adding some notes to the component's README.md file. You don't need to be an expert to share what youdo knowwith those who come afterwards. |
| 73 | |
| 74 | The same applies toclass level commentsand implementation comments.If you find yourself modifying codeand realizing that itis… under-documented.. feel free to add some notes nearby. |
| 75 | |
| 76 | In general,use your judgment.Changes will NOT be blocked on requiring people to add missing documentation, but adding missing docsis a great way to makeour codebase healthier. |
| 77 | |
| 78 | ## FAQ |
| 79 | |
| 80 | #### Are these hard rules? |
| 81 | |
| 82 | [Well,no](https://www.youtube.com/watch?v=jl0hMfqNQ-g). This said, following these guidelines will make our code base healthier, more consistent and much easier to understand. Over time improving in-code documentation will make the whole team faster. But if a small fix is genuinely needed (it almost always isn't), then don't block on writing detailed documentation. As always: use your judgment. |
| 83 | |
| 84 | #### I'm not an expert on this undocumented code, should I still add documentation? |
| 85 | |
| 86 | Yes!Partial documentationis much better thanno documentation. |
| 87 | |
| 88 | #### I hate writing documentation, it will slow me down! |
| 89 | |
| 90 | Chromiumis big enoughand complicated enough that a newcomer has to read a lot of code to figureout how things fit together.Documentation provides breadcrumbs to speed up understanding, which over time will make the whole team work more quickly.Short term execution speedis far less important thanlong term team velocity. |
