On Mon, Apr 18, 2022 at 18:50 Fujii Hironori via webkit-dev < webkit-dev@lists.webkit.org> wrote:
> > On Tue, Apr 19, 2022 at 6:55 AM Yusuke Suzuki via webkit-dev < > webkit-dev@lists.webkit.org> wrote: > >> I think this is important. We are using commit message / ChangeLog as a >> document tied to the change, and we are writing very detailed description >> to make the intention / design of the change clear and making it as a good >> document when we read the change via git-blame, bisect, using that header, >> investigating how it works etc. >> To make / keep this commit message / ChangeLog helpful, we need review, >> and I think reviewing of these messages is critical to keep usefulness of >> them. >> > > > I don't think commit messages and ChangeLogs are the best place for > technical descriptions. > We use them because we don't have a better place. > > libpas added the technical document in the repository in markdown. > > https://github.com/WebKit/WebKit/blob/main/Source/bmalloc/libpas/Documentation.md > > This makes it possible to change code and update the document in a single > commit, and get reviewed. > markdown is better than plain text. Updated documents are more useful than > the historical wiki pages. > It'd be nice if more documents are migrated into the repository. > Documentation gets obsolete relatively quickly. Code is the source of truth. A lot of comments in WebKit are either outdated, incorrect, and/or misleading. Change logs describe a change and thereby a specific point in time of the repository and wouldn't carry the same issue. It's also particularly useful to be able to see why a given line of code was written. Was it an oversight? On purpose? Or perhaps the required behavior different then and now? It's impractical and unproductive to add such a comment on every line of our codebase, and that level of online comment will add so much clutter to the codebase and would make it harder to read the code. - R. Niwa -- - R. Niwa
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org https://lists.webkit.org/mailman/listinfo/webkit-dev