Reading Code Is Hard
注: 以下内容引自: https://blogs.msdn.microsoft.com/ericlippert/2004/06/14/reading-code-is-hard/
Reading Code Is Hard
Escalation Engineer JeremyK asks in his blog this morning:
how do you teach people this “art” of digging deep very quickly into unfamilar code that you had no hand in writing? I myself, I come from a very traditional process of learning how to code, by sitting down and writing it. I am struggling with how to tailor a delivery to focus on reading vs. writing source code. To me the only way you can be truly efficient in this process is by having written code yourself.
No kidding Jeremy -- code is way easier to write than it is to read.
First off, I agree with you that there are very few people who can read code who cannot write code themselves. It's not like written or spoken natural languages, where understanding what someone else says does not require understanding why they said it that way. For example, if I were to say something like
"There are two recipes for producing code: a strict and detailed, and a vague and sloppy. The first produces elegant, tiered wedding cakes, the second, spaghetti."
you would understand what I meant to get across, without having to understand that I'm using the literary techniques of "zero anaphora" and "parallel clauses" to produce a balanced, harmonious effect in the listener/reader. Heck, you don't even have to know what a "verb" is to understand a sentence! But with code, it is vitally important that the both intention of the code's author and howthe code produces the intended effect be clear from the code itself.
Therefore, I would turn the question around -- how do we WRITE code that is more easily read by people who need to get up to speed very quickly on the code, but who didn't write any part of it?
Here are some of the things I try to do when writing code so that it can be more easily read:
- Make the code amenable to tools. Object browsers and Intellisense are great, but I'll tell you, I'm old school. If I can't find what I want via grep, I'm not happy. What makes code greppable?
- Variables with names like "i" are badness. You can't easily search code without getting false positives.
- Avoid making names that are prefixes of other names. For example, we have a performance marker in our code called "perfExecuteManifest", and another called "perfExecuteManifestInitialize". Drives me nuts every time I want to grep the source code for the former, I have to wade through all the instances of the latter.
- Use the same name for “tramp data” in both places. By tramp data, I mean those variables that you pass to a method only because they need to be passed on to another method. The two variables are basically the same thing, so it helps if they have the same name.
- Don't use macros that rename stuff. If the method is called get_MousePosition then don't declare it with a macro likeGETTER(MousePosition)-- because then I can't grep for the actual function name.
- Shadowing is evil. Please don't do it.
- Pick a consistent naming scheme. If you're going to use Hungarian, use it consistently and universally, otherwise it becomes an impediment rather than a benefit. Use Hungarian to document data semantics, not storage types. Use Hungarian to documentuniversal truths, not temporary conditions.
- Use assertionsto document preconditions and postconditions.
- Don't abbreviate English words. In particular, don't abbreviate them in really weird ways. In the script engines, the structure that holds a variable name is called NME. Drives me nuts! It should be called VariableName.
- The standard C runtime library is not a paragon of good library design. Do not emulate it.
- Don't write "clever" code; the maintenance programmers don't have time to figure out your cleverness when it turns out to be broken.
- Use the features of the language do to what they were designed to do, not what they can do. Don't use exceptions as a general flow control mechanism even though you can; use them to report errors. Don't cast interface pointers to class pointers, even if you know it will work. Etc.
- Structure the source code tree in functional units, not in political units. For example, on my team now the root subdirectories are "Frameworks" and "Integration", which are team names. Unfortunately, the Frameworks team now owns the Adaptor subdirectory of the Integration directory, which is confusing. Similarly, the various sub-trees have some subdirectories which are for client side components, some for server side components. Some for managed components, some for unmanaged components. Some for in-process components, some for out-of-proc components. Some for retail components, some for internal testing tools. It's kind of a mess. Of all the possible ways to organize a source tree, the political structure is the least important to the maintenance programmer!
Of course, I haven't actually answered Jeremy's question at all -- how do I debug code that I didn't write?
It depends on what my aim is. If I just want to dig into a very specific piece of code due to a bug, I'll concentrate on understanding data flow and control flow in the specific scenario I'm debugging. I'll step through all the code in the debugger, writing down the tree of calls as I go, making notes on which methods are produces and which are consumers of particular data structures. I'll also keep a watchful eye on the output window, looking for interesting messages going by. I'll turn on exception trapping, because usually exceptions are where the interesting stuff is, and because they can screw up your stepping pretty fast. I'll put breakpoints all the heck over the place. I'll make notes of all the places where my suggestions above are violated, because those are the things that are likely to mislead me.
If I want to understand a piece of code enough to modify it, I'll usually start with the headers, or I'll search for the public methods. I want to know what does this class implement, what does it extend, what is it for, how does it fit into the larger whole? I'll try to understand that stuff before I understand how the specific parts are implemented. That takes a lot longer, but you've got to do that due diligence if you're going to be making changes to complex code.
Reading Code Is Hard的更多相关文章
- Tips for newbie to read source code
This post is first posted on my WeChat public account: GeekArtT Reading source code is always one bi ...
- Code is not literature
http://www.gigamonkeys.com/code-reading/ I have started code reading groups at the last two companie ...
- Clean Code – Chapter 3: Functions
Small Blocks and Indenting The blocks within if statements, else statements, while statements, and s ...
- 一个简单的 Web 服务器 [未完成]
最近学习C++,linux和网络编程,想做个小(mini)项目. 就去搜索引擎, 开源中国, Sourceforge上找http server的项目. 好吧,也去了知乎. 知乎上程序员氛围好, ...
- [COPY] How to become a hacker
Engish version copied from here Why This Document? As editor of the Jargon File and author of a few ...
- RFID 读写器 Reader Writer Cloner
RFID读写器的工作原理 RFID的数据采集以读写器为主导,RFID读写器是一种通过无线通信,实现对标签识别和内存数据的读出和写入操作的装置. 读写器又称为阅读器或读头(Reader).查询器(Int ...
- Functions
Small The first rule of functions is that they should be small.The second rule of functions is that ...
- fw:学好Python必读的几篇文章
学好Python必读的几篇文章 from:http://blog.csdn.net/hzxhan/article/details/8555602 分类: python2013-01-30 11:52 ...
- 【译】C++工程师需要掌握的10个C++11特性
原文标题:Ten C++11 Features Every C++ Developer Should Use 原文作者:Marius Bancila 原文地址:codeproject 备注:非直译,带 ...
随机推荐
- nasm中的表达式
nasm表达式支持2个特殊的记号 $和$$;前者标识其所在源码行的开始处地址,所以你可以这样写死循环: jmp $ 而后者标识当前段开始处的地址,你可以通过: $-$$ 找出当前代码在段内的偏移. n ...
- 如何将windows格式的图标作为os x应用程序的图标
刚由windows转为os x的同学可能知道,在os x下我们想改变一个app的图标异常简单,直接打开该app的简介,然后将图标文件拖入简介窗口左上角图标方框即可.但是很多童鞋下载了一些图标文件后发现 ...
- was上的应用程序部分启动的原因
最近几天为了方便联调,我把两个项目配置到was测试环境上,前几天还好好的,昨天忽然有一个项目反复安装后都呈现部分启动的状态,打开节点一看,偏偏没启动的那个节点就是我需要用的79节点. 这让我很郁闷,硬 ...
- machine learning 之 Neural Network 2
整理自Andrew Ng的machine learning 课程 week5. 目录: Neural network and classification Cost function Backprop ...
- dsd
nodeName属性 nodeName属性规定节点的名称 nodeName是只读的 元素节点的nodeName与属性名相同 属性节点的nodeName与属性名相同 文本节点nodeName始终是#te ...
- java线程池原理
在什么情况下使用线程池? 1.单个任务处理的时间比较短 2.将需处理的任务的数量大 使用线程池的好处: 1.减少在创建和销毁线程上所花的时间以及系统资源的开销 ...
- Eclipse的优化
1. 取消系统的自动折叠 Window->Preferences-> Java->Editor->Folding: Enable folding 2. 取消按".&q ...
- LOVO学习之思维导图和文档编辑器
思维导图——是一种图示笔记方法,一种图示笔记工具,一个思考的利器.能将放射性思考具体化,帮助人们理解和记忆事物. 思维导图绘制规则:1,在纸的正中央用一个彩色图像或者符号开始画思维导图. 2,把所有主 ...
- App上线Check List
1.umeng统计.安全加固等第三方功能到位,本次上线市场列表选择好.2.后台数据库模式准备3.后台数据库数据准备4.后台应用服务器运行检查5.前端界面信息要正确6.前端交互不能出现过度卡顿和经常闪退 ...
- Web安全学习计划
http://cisps.org/bbs/viewtopic.php?f=71&t=26125 标题为Web安全学习计划,实属我的愿望:将下面这份Web学习清单完善成为一个Web安全,学习计划 ...