google / yapf

A formatter for Python files
Apache License 2.0
13.79k stars 892 forks source link

New format for human readers #705

Open arita37 opened 5 years ago

arita37 commented 5 years ago

Goal of formatting is to make faster code read for humans, and detect bugs...

What of you think of this format ?

image

VS this one

image

Formatting by block of code, especially aligning = , makes the code much faster to read.

kamahen commented 5 years ago

At Google, IIRC, this style was frowned upon because it is difficult to maintain. I never understood that reasoning because Emacs has the align-string command (also align-regexp and others). [I presume that vim has something similar]

However, it's tricky for an automated system to figure this alignment out ... look how much trouble yapf has in laying out dict-within-dict, for example.

My preference is to have no manual modification after running yapf. So, if I were writing a style guide, I'd frown upon aligning assignment statements, even though I personally prefer it. (Also, this kind of alignment tends to produce more line splits if the 80-column limit is preserved)

I should point out that the visual impact of spaces in natural languages is very much a cultural thing. Japanese and Chinese writing doesn't use spaces between "words"(*) and that doesn't seem to bother native speakers; Vietnamese puts a space between every syllable, even if if the syllables comprise a multi-syllable word(**). Which is to say: you can get used to anything and consider it "normal".

(Let the format religious wars begin!)

(*) The concept of "word" is surprisingly difficult in both Chinese and Japanese, even though the two languages are not related. A full explanation is beyond the scope of this note; the interested reader can find some research papers on this subject. (**) I'm using the notion of "non-productive compound" in the linguistic sense; that is, the meaning of the two syllables, when combined, is different from the meaning one would expect by just combining the meanings of the two syllables. For example, "black market" in English should be considered a single word (despite the spelling) because the meaning is not obvious from the two words "black" and "market".

arita37 commented 5 years ago

Thanks for sharing your view.

Yes, people can get used to any style, (ie assembly code).

My point was to consider the code in a grid (ie table where cell are assign logical piece of code). So, human can identify block of code easily. and get the logical and design easily.

Human spend too much time parsing the variable names, function arguments all together....

Splitting in the visualizing , make easily spot logical design mistake.

Maintaining may be difficult, automatic maintenance is easier....

On Apr 12, 2019, at 2:04, Peter Ludemann notifications@github.com wrote:

At Google, IIRC, this style was frowned upon because it is difficult to maintain. I never understood that reasoning because Emacs has the align-string command (also align-regexp and others). [I presume that vim has something similar]

However, it's tricky for an automated system to figure this alignment out ... look how much trouble yapf has in laying out dict-within-dict, for example.

My preference is to have no manual modification after running yapf. So, if I were writing a style guide, I'd frown upon aligning assignment statements, even though I personally prefer it. (Also, this kind of alignment tends to produce more line splits if the 80-column limit is preserved)

I should point out that the visual impact of spaces in natural languages is very much a cultural thing. Japanese and Chinese writing doesn't use spaces between "words"(*) and that doesn't seem to bother native speakers; Vietnamese puts a space between every syllable, even if if the syllables comprise a multi-syllable word(**). Which is to say: you can get used to anything and consider it "normal".

(Let the format religious wars begin!)

(*) The concept of "word" is surprisingly difficult in both Chinese and Japanese, even though the two languages are not related. A full explanation is beyond the scope of this note; the interested reader can find some research papers on this subject. (**) I'm using the notion of "non-productive compound" in the linguistic sense; that is, the meaning of the two syllables, when combined, is different from the meaning one would expect by just combining the meanings of the two syllables. For example, "black market" in English should be considered a single word (despite the spelling) because the meaning is not obvious from the two words "black" and "market".

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

bwendling commented 5 years ago

There is a SPACES_BEFORE_COMMENT option, which aligns comments. Aligning assignment operators could be done similarly I suppose.

arita37 commented 5 years ago

Main goal is to make the code as grid table : Align assingment, =, function

So, we catch within 1 sec, code flow and design issues.

Think more work should be done to enhance fast readibility of code...

On Jul 16, 2019, at 16:51, Bill Wendling notifications@github.com wrote:

There is a SPACES_BEFORE_COMMENT option, which aligns comments. Aligning assignment operators could be done similarly I suppose.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

arita37 commented 2 years ago

Just wondering, if people have any interest in reading code with aligned statements