5 ms·

Is there a reason why it seems there is so little documentation/comments in source files of WebKit? Or maybe I'm missing something/opened the wrong files.

by doe88 4y ago

mnutt 4y ago
Documentation has been a bit of a challenge in my experience. There are some high-level docs at https://trac.webkit.org/wiki https://trac.webkit.org/wiki though many are 10-15 years old at this point. My approach has been to look at the commit history for the file to see if the changesets shed any light, and sometimes go to the attached bugzilla link to see if there was any discussion about the change there. Then attach a debugger and step through to try to uncover how the classes relate to one another.
tuankiet65 4y ago
You aren't opening the wrong file, there isn't much documentation in WebKit besides a few Markdown files. I'm not sure why this is the case.
saagarjha 4y ago
Most WebKit developers are good at documentation, it’s just that they often work on things that their employer would not like being made obvious because it deals with SPI or unreleased products or security vulnerabilities. Commit messages are actually pretty good for the most part except in these situations where a laconic or purposefully misleading message will be used.
domenicd 4y ago
There's some policy about comments being bad / code should be self documenting. From what I hear from my colleagues on the Chrome team, one of the first things they were delighted to do after forking Blink was to finally go around and comment the various confusing parts of the codebase. (And, no longer get requests to remove comments when trying to land a PR.)
- habosa 4y ago
  I've met some very smart and capable programmers who perpetuate this "style". It's so harmful. Comments are good for the writer AND the reader.
- doe88 4y ago
  Thanks, for the reply, what such a weird policy. I found it so uncanny at first, that I even thought that they had somehow internally a system where they were able to automatically merge some comments and documentation with their source files.

Is there a reason why it seems there is so little documentation/comments in source files of WebKit? Or maybe I'm missing something/opened the wrong files.

by doe88 4y ago

Is there a reason why it seems there is so little documentation/comments in source files of WebKit? Or maybe I'm missing something/opened the wrong files.

mnutt 4y ago

Documentation has been a bit of a challenge in my experience. There are some high-level docs at https://trac.webkit.org/wiki https://trac.webkit.org/wiki though many are 10-15 years old at this point. My approach has been to look at the commit history for the file to see if the changesets shed any light, and sometimes go to the attached bugzilla link to see if there was any discussion about the change there. Then attach a debugger and step through to try to uncover how the classes relate to one another.

tuankiet65 4y ago

You aren't opening the wrong file, there isn't much documentation in WebKit besides a few Markdown files. I'm not sure why this is the case.

saagarjha 4y ago

Most WebKit developers are good at documentation, it’s just that they often work on things that their employer would not like being made obvious because it deals with SPI or unreleased products or security vulnerabilities. Commit messages are actually pretty good for the most part except in these situations where a laconic or purposefully misleading message will be used.

domenicd 4y ago

There's some policy about comments being bad / code should be self documenting. From what I hear from my colleagues on the Chrome team, one of the first things they were delighted to do after forking Blink was to finally go around and comment the various confusing parts of the codebase. (And, no longer get requests to remove comments when trying to land a PR.)

habosa 4y ago
I've met some very smart and capable programmers who perpetuate this "style". It's so harmful. Comments are good for the writer AND the reader.
doe88 4y ago
Thanks, for the reply, what such a weird policy. I found it so uncanny at first, that I even thought that they had somehow internally a system where they were able to automatically merge some comments and documentation with their source files.