当前位置:网站首页>How to write code that people can easily read?

How to write code that people can easily read?

2021-07-14 16:52:03 InfoQ

{"type":"doc","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" There is a popular saying that : The code is written for people to read , Not for the execution of the machine . However , Write code that's easy for humans to read , It's easier said than done . It will take years to learn , It takes decades to master . I might be able to offer a shortcut : Think about code quality like an educator ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"“ shortcut ” It's a powerful word . It's not a shortcut . but "},{"type":"link","attrs":{"href":"https:\/\/medium.com\/@adamzerner\/representation-matters-f46d7acf8786?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":" In my submission "}]},{"type":"text","text":", This view is important .Alan Kay"},{"type":"link","attrs":{"href":"https:\/\/www.quora.com\/What-did-Alan-Kay-mean-by-A-change-of-perspective-is-worth-80-IQ-points?share=1&fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":" Said "}]},{"type":"text","text":", The point of view is worth 80 A little bit of intelligence ."}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":" Know your audience "}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"Rails"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" At work , We use Rails、Node and Vue. The main application uses Rails Written , Part of the front end is with Vue Written , And then we use Node I wrote some lambda function . In the ideal world ,Rails People write Rails,Node People write Node,Vue People write Vue, But this is not the case . actually , We're going to have this situation :Node and Vue People have to read or write Rails Code ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" To put it mildly ,Rails It's a weird frame , A lot of strange things happen , Convention over configuration . for example , If you see the following code :"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"# app\/controllers\/api\/foo\/bar\/baz_controller.rb\n\ndef show\nend"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"Rails Will be automatically "},{"type":"codeinline","content":[{"type":"text","text":"app\/views\/api\/foo\/bar\/baz"}]},{"type":"text","text":" Look inside "},{"type":"codeinline","content":[{"type":"text","text":"show.html.erb"}]},{"type":"text","text":" or "},{"type":"codeinline","content":[{"type":"text","text":"show.jbuilder"}]},{"type":"text","text":" In response . But if you're not a Rails developer ... You don't know that ! All you see is an empty method , It seems to have done nothing ! what's more , You can't figure it out . The answer is not hidden in some parent class or mixin in , It's hidden in this "},{"type":"link","attrs":{"href":"https:\/\/guides.rubyonrails.org\/?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":" A Book of tribal knowledge "}]},{"type":"text","text":" in ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I'm not sure about this controller actions The example of is not a good example . actually , It's something you'll soon learn , Or someone on your team can find out and help you right away . But in other cases , You can use it. Rails Do something weird , And only those who happen to have this tribal knowledge can understand ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" When you work in an experienced Rails In the team work of experts , It's not a problem . in fact , These weird things can help Rails Experts become more efficient . however , If you work in a right Rails When it's all a novice team , These rookies will definitely fall into despair and depression ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" This is where you need to think like an educator . Suppose you are a professor . If you stand in front of a small group of doctors , Hold a highly specialized 、 Centralized seminars , You can use fancy terms and so on without worrying that they are beyond the audience's knowledge . however ... If you find yourself standing in a lecture hall facing a group of undergraduates , that , Using these terms is not a wise choice ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" about Rails In the same way . The problem is not that something is “ Best practices ” still “Rails programmatically ”, It's about whether it makes sense to your audience ."}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"Angular"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I "},{"type":"link","attrs":{"href":"https:\/\/adamzerner.bearblog.dev\/using-obscure-features-of-a-programming-language\/?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":" I've made this mistake in the past "}]},{"type":"text","text":". In a former company , We use Rails、Angular and Python. I'm the one “ Use Angular The guy who ”. Most of the rest of the team are Rails personnel ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I am to myself, to directives I feel a little proud of the use of . But my boss told me to stop using these things , Stick to the normal controllers. He even mentioned , His reason is that this is the programming way most software developers expect to see if they enter a code base ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" at that time , I think it's obvious , He's wrong . What I saw Anguar All the videos and books written by experts , All told me these are best practices . They're all experts , And they seem to know better than my boss Angular, So I think I should trust these experts, not my boss . At least that's what I think ."}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"ELI5"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" stay 《 Why functional programming is important 》 In a Book ,Eric Normand"},{"type":"link","attrs":{"href":"https:\/\/youtu.be\/eagJJs_Ysos?t=3048&fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":" When it comes to the "}]},{"type":"text","text":" A game tree program . He said , In College , He uses a pile of "},{"type":"codeinline","content":[{"type":"text","text":"for"}]},{"type":"text","text":" Loop wrote a similar program . then , He talked about the approach taken by the author of a paper :"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"blockquote","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"italic"}],"text":" His solution , It's simpler, of course , yes ... Very concise . Very concise . I don't know if I can read it ."}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" This shows some problems , because Eric Normand I'm an expert in functional programming . If your code is too concise , Even domain experts have a hard time understanding it , So this may not be the goal you should pursue . In the same podcast ,Normand Rethinking functional programming languages \/ Is the code too concise ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" It reminds me of EliezerYudkowsky stay 《"},{"type":"link","attrs":{"href":"https:\/\/www.lesswrong.com\/posts\/2TPph4EGZ6trEbtku\/explainers-shoot-high-aim-low?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":"Explainers Shoot High. Aim Low!"}]},{"type":"text","text":"》 There's something in it :"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"blockquote","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"italic"}],"text":" A few years ago , A famous scientist once told me , How he wrote an explanatory article for his field at a much lower technical level than usual . He thinks it's important for scholars outside the field , Even the reporter , It's going to work . This paper eventually became one of the most popular in his field , More cited than any other article he's written ."},{"type":"text","marks":[{"type":"italic"}],"text":" It's not that his fellow scientists are stupid , It's that we tend to greatly underestimate the effort required to understand things correctly ."}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I think it's a good thing to remember that when writing code ."}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":" Lower the level ?"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"“ Know your audience ” It doesn't necessarily mean you need to lower everything to a lower level ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Think of university professors teaching undergraduates . At the beginning of the semester , It may take time , Be very careful in explaining things . however , As specific terms and concepts become familiar to the class , It might be better to use these terms freely ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Again , When there are some terms and concepts that are difficult to understand , It may make more sense to introduce these concepts slowly rather than avoid them completely , So students can learn these concepts and use them in the future ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I think the key to the problem is , As usual , It's about trade-offs , You need to be aware of these issues and consider them in your decisions ."}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":" visualization "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" What tools educators use to teach ? Slide 、 textbook 、 Lecture video 、 demonstration 、 test 、 Office hours 、 homework 、 Chart 、 simulation , wait . When we write code , Are these tools useful to our developers ?"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Some of them are not applicable . for example , A complete teaching video . Others are a little silly . for example , test . however , I think at least some tools are available ."}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":" videotape "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Let's rethink the lecture video . For everything you write 10 Line function code , It's unrealistic to give an in-depth explanation . But for larger code blocks ? For one lambda Function or an important module , I think it makes sense ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" in fact , I think something similar has happened . When dealing with parts of the code base that you're not familiar with , One of my favorite tips is to use "},{"type":"codeinline","content":[{"type":"text","text":"git blame"}]},{"type":"text","text":" To improve your understanding of the code . I'll see who wrote most of the code , stay Slack Upper communication , And then they'll spend about 20 Give me five minutes to give a general explanation . I think it's very useful . that , Why not record an explanation like this , And link to this explanation in the form of code comments at the head of the file ?"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I think the biggest reason is maintainability . As the code base evolves , Video will become obsolete . When things like code comments become obsolete , It's easy to edit them , But for a video , You can't really edit from 17:34 To 21:40 Fragments of . At least it's not easy ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I have some objections to this view . Yes , It will eventually get old , But so what ? If the code changes are small , The video will not be out of date , The benefits outweigh the costs . If the code changes a lot , Then you can spend more 20 Minutes to record a presentation . Even for any reason , The team is not synchronized , Finally, the video is not updated when the code changes a lot , And I don't think it's going to cause any major damage . If someone clicks on it and starts watching , They will soon realize that this video is out of date and stop watching it ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Another point I'm against is that it's time-consuming to record videos . That's bullshit . We've spent a lot of time trying to produce high quality code : The early stage of the work 、 restructure 、 Code review , wait . flowers 20 Minute time , Explain to the camera in a random stream of consciousness , Compared to the other time you spend . I think the real point of this view is , Recording a video feels like a big thing to do ."}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":" Chart "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" ok , Let's look at the other tools , How about the chart ? I think the chart is great ! Fortunately, , They have been adopted by some people . Especially at the architecture level , To show how different modules connect to another module ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https:\/\/static001.geekbang.org\/infoq\/ff\/ffd0376fcccc9e8aa2a7b78f724d365e.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" However , I feel like charts are still underutilized ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Here is an example , Shows how to use it for transactions at a lower architecture level . about “"},{"type":"link","attrs":{"href":"https:\/\/leetcode.com\/problems\/container-with-most-water\/?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":" The container with the most water capacity "}]},{"type":"text","text":"” problem , The following visual references can be very useful :"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https:\/\/static001.geekbang.org\/infoq\/30\/306224ca03ef895fc609388976cb6b34.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" in my opinion , The area of front-end code is one where diagrams are especially underutilized . I think it's cool to have charts next to the code , So you can put a picture to show a React What components look like . Yes , You may have opened a web page by , And use inspection tools ( Or just through common sense ) To determine which code corresponds to which UI, But it's going to be a little awkward . Maybe it's a good idea to cut down on these little quirks ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" In particular, I think of the following . You should have this plug-in in your text editor . When your text editor sees a code comment followed by a "},{"type":"codeinline","content":[{"type":"text","text":".jpg"}]},{"type":"text","text":" At the end of the URL"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"\/\/ https:\/\/example.com\/code-images\/modal.jpg"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" It will have a small fold on the left \/ Expand the arrow , When you click Show , It will show pictures in-line ! I think it will be much more convenient ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" My friend "},{"type":"link","attrs":{"href":"https:\/\/www.brendanlong.com\/pages\/about-me.html?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":"Brendan Long"}]},{"type":"text","text":" There's a good idea : Use some plug-in to automatically generate these charts or pictures based on some simulation data of these components ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" All in all , It's not just a strong personal feeling , It's a guess , But it's really interesting !"}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"Clean code"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Let's get rid of marginal topics like videos , Back to a world we know better . In this world , We try to write code in a way that's easier for others to understand ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https:\/\/static001.geekbang.org\/infoq\/c6\/c6f10f19551e109c1adf637e32bbb2e8.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" As I said at the beginning of the article , If you think of yourself as someone who teaches the rest of the team how to use this code , quite a lot "},{"type":"link","attrs":{"href":"https:\/\/www.amazon.com\/Clean-Code-Handbook-Software-Craftsmanship\/dp\/0132350882?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":" Recognized "}]},{"type":"text","text":" About clean code All the ideas come naturally . Descriptive variable name 、 modularization 、 Appropriate indentation , wait . I also from "},{"type":"link","attrs":{"href":"https:\/\/github.com\/ryanmcdermott\/clean-code-javascript?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":"clean-code-javascript"}]},{"type":"text","text":"“ borrow ” Here are some examples ."}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":" Bad code "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"\/\/ What the heck is 86400000 for?\nsetTimeout(blastOff, 86400000);"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":" Good code "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"\/\/ Declare them as capitalized named constants.\nconst MILLISECONDS_IN_A_DAY = 60 * 60 * 24 * 1000; \/\/86400000;\n\nsetTimeout(blastOff, MILLISECONDS_IN_A_DAY);"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":" Bad code "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"const address = \"One Infinite Loop, Cupertino 95014\";\nconst cityZipCodeRegex = \/^[^,\\\\]+[,\\\\\\s]+(.+?)\\s*(\\d{5})?$\/;\nsaveCityZipCode(\n address.match(cityZipCodeRegex)[1],\n address.match(cityZipCodeRegex)[2]\n);"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":" Good code "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"const address = \"One Infinite Loop, Cupertino 95014\";\nconst cityZipCodeRegex = \/^[^,\\\\]+[,\\\\\\s]+(.+?)\\s*(\\d{5})?$\/;\nconst [_, city, zipCode] = address.match(cityZipCodeRegex) || [];\nsaveCityZipCode(city, zipCode);"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":" Bad code "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"function emailClients(clients) {\n clients.forEach(client => {\n const clientRecord = database.lookup(client);\n if (clientRecord.isActive()) {\n email(client);\n }\n });\n}"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":" Good code "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"function emailActiveClients(clients) {\n clients.filter(isActiveClient).forEach(email);\n}\nfunction isActiveClient(client) {\n const clientRecord = database.lookup(client);\n return clientRecord.isActive();\n}"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":" Bad code "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"function addToDate(date, month) {\n \/\/ ...\n}\nconst date = new Date();\n\/\/ It's hard to tell from the function name what is added\naddToDate(date, 1);"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong"}],"text":" Good code "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"function addMonthToDate(month, date) {\n \/\/ ...\n}\nconst date = new Date();\naddMonthToDate(1, date);"}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":" code annotation "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I prefer the traditional way of writing log comments "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"\/**\n * 2016-12-20: Removed monads, didn't understand them (RM)\n * 2016-10-01: Improved using special monads (JP)\n * 2016-02-03: Removed type-checking (LI)\n * 2015-03-14: Added combine with type-checking (JR)\n *\/\nfunction combine(a, b) {\n return a + b;\n}"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Location marks "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\n\/\/ Scope Model Instantiation\n\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\n$scope.model = {\n menu: \"foo\",\n nav: \"bar\"\n};\n\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\n\/\/ Action setup\n\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\nconst actions = function() {\n \/\/ ...\n};"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Obvious notes "}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"plain"},"content":[{"type":"text","text":"function hashIt(data) {\n \/\/ The hash\n let hash = 0;\n\n \/\/ Length of string\n const length = data.length;\n\n \/\/ Loop through every character in data\n for (let i = 0; i < length; i++) {\n \/\/ Get character code.\n const char = data.charCodeAt(i);\n \/\/ Make the hash\n hash = (hash << 5) - hash + char;\n \/\/ Convert to 32-bit integer\n hash &= hash;\n }\n}"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" You should avoid using positional and explicit annotations like this . However , I'm concerned about “"},{"type":"link","attrs":{"href":"https:\/\/github.com\/ryanmcdermott\/clean-code-javascript?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":" Good code is usually its own documentation "}]},{"type":"text","text":"” There are reservations about this . I usually default on the assumption that :"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"bulletedlist","content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I've noticed that people use explanatory notes in their work , And I don't do that in those scenes , But I find these annotations really useful ;"}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" such “ Think like an educator ” I think they are very valuable ."}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" I don't want to argue that these annotations are underutilized . That's hard . contrary , I just want to suggest that you reevaluate your position accordingly . The next time you write a function , Ask yourself , Is there anyone else who will have a hard time understanding the code you're writing . Ask yourself , Whether you can add some comments that won't appear redundant and bloated . Ask yourself , What an educator would do ."}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":" Postscript : Think like a usability designer ?"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" This article is about thinking like an educator when you write code . I think it's a good idea , But is that the only good idea ? Fill in the blanks :“ Like a ____ Think about code quality the same way ”. Any other meaningful ideas ?"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" The most important thing that comes to mind is “ Usability designers ”. Why? ? Because I always thought , User testing is something that people should do in the code base !"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" think about it , What I said in the last paragraph of the document :"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"blockquote","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Ask yourself , Is there anyone else who will have a hard time understanding the code you're writing "}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Usability designers have been doing this kind of thing ! It's their job ! But not only that , What else do they do ?"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"link","attrs":{"href":"https:\/\/blog.codinghorror.com\/low-fi-usability-testing\/?fileGuid=rU8e3yc0h4Mztn6T","title":"","type":null},"content":[{"type":"text","text":" User testing "}]},{"type":"text","text":"! They don't just assume that people will understand how to use their products . They're going to test . Put it in front of real users , Let's see what's weird . Why can't we do the same with code ?"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":" Link to the original text :"}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"https:\/\/adamzerner.bearblog.dev\/think-like-an-educator-about-code-quality\/?fileGuid=rU8e3yc0h4Mztn6T"}]}]}

版权声明
本文为[InfoQ]所创,转载请带上原文链接,感谢
https://chowdera.com/2021/07/20210714165058803d.html

随机推荐