thing_13

Code Layout Matters
https://97-things-every-x-should-know.gitbooks.io/97-things-every-programmer-should-know/content/en/thing_13/
An infeasible number of years ago I worked on a Cobol system where staff weren’t allowed to change the indentation unless they already had a reason to change the code, because someone once broke something by letting a line slip into one of the special columns at the beginning of a line. This applied even if the layout was misleading, which it sometimes was, so we had to read the code very carefully because we couldn’t trust it. The policy must have cost a fortune in programmer drag.

There’s research to show the we all spend much more of our programming time navigating and reading code — finding where to make the change — than actually typing, so that’s what we want to optimize for.

• Easy to scan. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the savannah), so I can help myself by making everything that isn’t directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardizing it. If code that behaves the same looks the same, then my perceptual system will help me pick out the differences. That’s why I also observe conventions about how to lay out the parts of a class within a compilation unit: constants, fields, public methods, private methods.

• Expressive layout. We’ve all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps — right? The code’s layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basics, then I might make adjustments by hand while I’m coding. Unless there’s active dissension, a team will quickly converge on a common “hand-finished” style. A formatter cannot understand my intentions (I should know, I once wrote one), and it’s more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language. (Kevin McGuire freed me from my bondage to automatic code formatters.)

• Compact format. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8-character names and line printers, but now I live in an IDE that does syntax coloring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.

A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it’s there to help me understand the idea. Unfortunately, writing code doesn’t have the same romantic image as writing poetry.

By Steve Freeman

几年前，我在一个Cobol系统中工作，在这个系统中，工作人员不允许更改缩进，除非他们已经有理由更改代码，因为有人曾经让一行滑到一行开头的一个特殊列中，从而破坏了一些东西。即使布局有误导性，这也是适用的，有时确实如此，所以我们必须非常仔细地阅读代码，因为我们不能相信它。该策略一定在程序员的拖延中花费了一大笔钱。
有研究表明，我们在编程时花在导航和阅读代码上的时间比实际打字要多得多，所以这就是我们想要优化的地方。
易于扫描。人们真的很擅长视觉模式匹配（这是我们不得不在大草原上发现狮子时的遗留问题），所以我可以通过标准化来帮助自己，让所有与该领域不直接相关的东西，以及大多数商业语言所带来的所有“偶然复杂性”，消失在背景中。如果行为相同的代码看起来相同，那么我的感知系统将帮助我找出差异。这就是为什么我也遵守关于如何在编译单元中布置类的部分的约定：常量、字段、公共方法、私有方法。
富有表现力的布局。我们都学会了花时间找到正确的名称，这样我们的代码就可以尽可能清楚地表达它的作用，而不仅仅是列出步骤——对吧？代码的布局也是这种表现力的一部分。第一步是让团队就基本的自动格式化程序达成一致，然后我可能会在编码时手动进行调整。除非有积极的分歧，否则团队很快就会形成一种共同的“手工完成”风格。格式化程序无法理解我的意图（我应该知道，我曾经写过一个），对我来说更重要的是，换行和分组反映了代码的意图，而不仅仅是语言的语法。（Kevin McGuire让我摆脱了对自动代码格式化程序的束缚。）
紧凑格式。我在屏幕上看得越多，就越能在不破坏上下文的情况下滚动或切换文件，这意味着我可以在脑海中保持更少的状态。长的过程注释和大量的空白对于8个字符的名称和行打印机来说是有意义的，但现在我住在一个做语法着色和交叉链接的IDE中。像素是我的限制因素，所以我希望每个像素都能帮助我理解代码。我希望布局能帮助我理解代码，但仅此而已。
一位非程序员的朋友曾经说过，代码看起来像诗歌。我从真正优秀的代码中得到了这种感觉，文本中的一切都有目的，它可以帮助我理解这个想法。不幸的是，编写代码并不像写诗那样浪漫。
作者Steve Freeman