🙂/🙁 Blink Code Complexity Survey (complain about what makes working in Blink hard)

[Jeremy Roman]

Hey there, Blink-folk!

The results of an internal survey suggest that many of us feel hindered by technical debt and overly complicated code.

We want to know what slows you down while developing web platform code in Chromium.

Befuddled by garbage collection? Tell us!

Sick and tired of writing yet another wrapper class? Let us know!

Please fill out this survey:

https://goo.gl/forms/jRJLSzBcVcPTlIUz2

We'll share the results after the survey closes.

[Jeremy Roman]

Hello again, results are in. The short version is, we have some work to do, especially around documentation and code structure.

Presentation summary (BlinkOn slides): https://docs.google.com/presentation/d/1LIR5gA9Sg-bejvRaB5F1EqNq6mLf5hMYcNiHGQyj6ag/edit?usp=sharing

This talk should have been recorded, and so a video will eventually be released.

Automatic response summary: https://docs.google.com/forms/d/16o41lqUNS2Fzy3Km5Pm8j-DVM41_AdXgYNE0E9yM8ig/viewanalytics

Raw responses spreadsheet: https://docs.google.com/spreadsheets/d/1BqCAu7dPUyK5ZYePBD0efVUfyk7aE4DL9uSZYLbAdQY/edit?usp=sharing

We intend to also fan out some team-specific comments to the relevant team mailing lists.

[Daniel Bratell]

I would like to know what kind of documentation that is missing. Is it high level Chromium architecture, or class/algorithmic comments? I know both are missing, but what do those that clicked "need better documentation" think about when they clicked it?

One thing everyone seems to agree on is that the old idea that inline comments are meaningless because code should be self explanatory is not a good idea.

Code should be self explanatory, in the way that you should always see what the code is doing, but comments are needed to explain why something is a good idea and what the code intends to do. Especially in the web platform code, knowing that something is done tells you little about why it should be done.

Personally I do miss high level architecture docs. Just the other day I was trying to find anything written about components and services and failed badly. Wherever that is documented, it is not easy to find. And the outcome of the platform discussion, will it be put in print anywhere "official"?

/Daniel

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CACuR13eexUCnzrTbG_icvm%3DXc9cuCyxWXziOftsqj1kcpeC6xA%40mail.gmail.com.

--

/* Opera Software, Linköping, Sweden: CEST (UTC+2) */

[Jeremy Roman]

On Tue, Apr 24, 2018 at 12:13 PM, Daniel Bratell <bra...@opera.com> wrote:

I would like to know what kind of documentation that is missing. Is it high level Chromium architecture, or class/algorithmic comments? I know both are missing, but what do those that clicked "need better documentation" think about when they clicked it?

One thing everyone seems to agree on is that the old idea that inline comments are meaningless because code should be self explanatory is not a good idea.

Code should be self explanatory, in the way that you should always see what the code is doing, but comments are needed to explain why something is a good idea and what the code intends to do. Especially in the web platform code, knowing that something is done tells you little about why it should be done.

I saw comments across the board: how large systems were difficult to understand, how many specific classes were missing what-is-this header comments, and how sometimes a bit of logic is non-obvious and yet undocumented. 

 

Personally I do miss high level architecture docs. Just the other day I was trying to find anything written about components and services and failed badly. Wherever that is documented, it is not easy to find. And the outcome of the platform discussion, will it be put in print anywhere "official"?

If you mean the role of platform/, I would consider the README.md files in platform/ and its parent to be the "official" source.

 

/Daniel

On Fri, 20 Apr 2018 22:55:18 +0200, Jeremy Roman <jbr...@chromium.org> wrote:

Hello again, results are in. The short version is, we have some work to do, especially around documentation and code structure.

Presentation summary (BlinkOn slides): https://docs.google.com/presentation/d/1LIR5gA9Sg-bejvRaB5F1EqNq6mLf5hMYcNiHGQyj6ag/edit?usp=sharing

This talk should have been recorded, and so a video will eventually be released.

Automatic response summary: https://docs.google.com/forms/d/16o41lqUNS2Fzy3Km5Pm8j-DVM41_AdXgYNE0E9yM8ig/viewanalytics

Raw responses spreadsheet: https://docs.google.com/spreadsheets/d/1BqCAu7dPUyK5ZYePBD0efVUfyk7aE4DL9uSZYLbAdQY/edit?usp=sharing

We intend to also fan out some team-specific comments to the relevant team mailing lists.

On Tue, Mar 20, 2018 at 7:32 AM, Jeremy Roman <jbr...@chromium.org> wrote:

Hey there, Blink-folk!

The results of an internal survey suggest that many of us feel hindered by technical debt and overly complicated code.

We want to know what slows you down while developing web platform code in Chromium.

Befuddled by garbage collection? Tell us!

Sick and tired of writing yet another wrapper class? Let us know!

Please fill out this survey:

https://goo.gl/forms/jRJLSzBcVcPTlIUz2

We'll share the results after the survey closes.

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CACuR13eexUCnzrTbG_icvm%3DXc9cuCyxWXziOftsqj1kcpeC6xA%40mail.gmail.com.

[Kentaro Hara]

+1 to getting to the state where people can get necessary info by looking at README.md. README.md doesn't need to describe all info but at least should have pointers to necessary info.

--
You received this message because you are subscribed to the Google Groups "platform-architecture-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to platform-architecture-dev+unsub...@chromium.org.
To post to this group, send email to platform-architecture-dev@chromium.org.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/platform-architecture-dev/CACuR13cZsDUaEaozAKN%3DbiVeunfW3CQ_iqGK1O1Nq-dksFAP7g%40mail.gmail.com.

--

Kentaro Hara, Tokyo, Japan

[Daniel Vogelheim]

I think a big part of the problem is that we don't even have a shared understanding of what documentation is good documentation.

Class comments usually only help when I already know this is the class I need to use. But more often, the problem I have is that I'm not sure what I should be using in the first place.

My entry point to documentation is pretty much always that I need to do something outside of the code I usually work on, but am not sure how. Going from 'I have a problem' to finding the right doc (and being sure the doc is current) is often time consuming. I agree we need 'high level' docs; but the specific problem I often have is that docs are (partly) outdated and that docs aren't usable as reference docs (that is, I can't find & skip to the part pertaining to my problem, and I'd have to read the entire doc first to figure out whether it applies to my problem or not). Both issues are probably trivial to navigate for people familiar with topic being covered - e.g., for my own code, I can map the doc title to the problem space, and also know whether any large-ish changes happened after a given doc was written. But for areas I don't know well, I can't do either of those things.

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CACuR13eexUCnzrTbG_icvm%3DXc9cuCyxWXziOftsqj1kcpeC6xA%40mail.gmail.com.

--

/* Opera Software, Linköping, Sweden: CEST (UTC+2) */

--

You received this message because you are subscribed to the Google Groups "blink-dev" group.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/op.zhzgpfwarbppqq%40cicero2.linkoping.osa.

[Fergal Daly]

I moved to chrome in January and really felt the lack of docs of several types

- high level,- for this subsystem, here's how the whole process works, the overall flow and the relationship between things

- class level - what is the purpose of this class? what is it's intended lifecycle? why do this class and 2 other classes have suspiciously similar names?

- method level - what's it supposed to do, e.g. when is it expected to return nullptr. I can't tell if it has a bug if the code is the documentation.

- inline - at least for the code I've worked with, this is almost the only type of documentation that exists in any amount

F

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CACuR13eexUCnzrTbG_icvm%3DXc9cuCyxWXziOftsqj1kcpeC6xA%40mail.gmail.com.

--

/* Opera Software, Linköping, Sweden: CEST (UTC+2) */

--

You received this message because you are subscribed to the Google Groups "blink-dev" group.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/op.zhzgpfwarbppqq%40cicero2.linkoping.osa.

[Kentaro Hara]

I want to ask a couple of questions here.

We discussed this topic at BlinkOn7 and agreed on the following guideline. The guideline is written in Blink C++ Style Guideline (though it looks like it was reworded after I wrote it).

1) Directories should have README.md, which describes a high-level design and structure of the component.

2) Classes should have a class-level comment.

3) Non-trivial code should have a comment.

4) Documentation-only changes may be TBR-ed.

Operation-wise, the plan was to force the guideline for new code and encourage individual teams to add more comments to existing code they own. I know many people have executed this but we're far away from the end state.

Q: Once 1) - 3) are achieved, do you think that Blink's documentation is good? If not, why?

Q: Do you think that 1) - 3) are asking too much? On one hand, many people say that Blink lacks documentation. On the other hand, we know the cost of writing and maintaining the documentation. If 1) - 3) are too much, what would be a good balance point?

Q: How do you think we can operationalize the documentation efforts in a better way? Is it a tooling problem? Should we train reviewers more?

--

You received this message because you are subscribed to the Google Groups "platform-architecture-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to platform-architecture-dev+unsub...@chromium.org.
To post to this group, send email to platform-architecture-dev@chromium.org.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/platform-architecture-dev/CAAozHL%3DhdHKOsp3Cof8EFxfRQiMq9UkbANXQso6DQFWWPy81eQ%40mail.gmail.com.

[jeng...@gmail.com]

Fix