代码中没有任何评论我被要求修复 - 没有任何一个 [英] No comments in code i was asked to fix - none whatsoever

问题描述

我刚刚完成了一年多的修复一些严重损坏的代码（DB /前端的东西）并完全没有评论。



为了使事情变得更加棘手，无论是谁写的都是隐藏变量名的忠实粉丝，它们绝不描述其目的或功能。一个名为'ip'的变量是什么意思？在这种特殊情况下，它指的是一个内部计数器，用于跟踪货物托盘中有多少物品。不完全直观。



我的问题是，这是正常的吗？他们只是懒惰吗？或者他们试图隐藏什么东西？



在我自己的代码中，我记录了我想要实现的一切，绊倒了什么，我是怎么回事感觉 - 基本上是我在那个特殊的日子里穿的袜子和内衣。



我的导师在我脑海里鼓掌：令人惊讶的是你在一个月，更不用说一年了，所以记录，记录一切。



所以无论如何，我只是想知道这是不是常态。感谢您阅读我的迷你咆哮。现在我已经修好了我要回来申请的所有东西。



我尝试了什么：



描述性变量名称，为方法添加解释性总结，尽我所能创建自描述代码

I've just recently finished just over a year's worth of fixing some seriously broken code (DB/Front end stuff) and it was completely devoid of comments.

To make things even trickier, whoever wrote it was a big fan of cryptic variable names which in no way described their purpose or function. What does a variable called (say) 'ip' mean? in this particular case it referred to an internal counter used for tracking how many items belonged to a pallet of goods. Not exactly intuitive.

My question is, is this normal? Were they just lazy? Or were they trying to hide something?

In my own code, I document everything from what I'm trying to achieve, what's tripped me up, how I'm feeling - basically down to the socks and undies I'm wearing on that particular day.

My tutor drummed into my head that: It's suprising what you can forget in a month, let alone a year, so document, document everything.

So anyway, I just wondered if this was the norm. Thanks for reading my mini rant. Now that I've fixed everything I'm back applying for the dole.

What I have tried:

Descriptive variable names, adding explanatory summarys to methods, doing my very best to create self-descriptive code

推荐答案

人类思维工作以一种神秘的方式。开发人员可能是懒惰的，或者可能只是认为他们命名的变量在各自的上下文中具有足够的描述性。这就是为什么它需要通过代码审查或配对编程来获得第二双眼睛。你有这个问题，我不会说它是正常的，它永远不会成为标准，但我已经看到它经常发生。



文件是必要的描述你写的代码。现在，您应该如何做到这一点取决于目标受众，最有可能是其他开发人员。文档应该描述3件事。



1.你需要告诉 是什么方法。

2你需要告诉为什么写这个方法。

3.你需要告诉 目标是什么。



现在，这些可以通过多种方式实现。我所遵循的是将我的方法命名为足够描述，以便描述what。在每个方法的顶部添加注释，其中为什么需要该方法。将我的变量命名为足够合理，以便how实现目标变得明显。

Human mind works in a mysterious way. The developer might be lazy or might just think whatever they named the variables are descriptive enough in the respective context. That is why it needs a second pair of eyes either through code review or pair programming. The problem you have, I wouldn't say it is normal and it can never be the standard, but I have seen it happening quite frequently.

Documentation is necessary for describing the code you have written. Now, how you should do it depends on the target audiences, most likely to be other developers. The documentation should describe 3 things.

1. You need to tell what is the method.
2. You need to tell why this method is written.
3. You need to tell how the goal has been achieved.

Now, these can be achieved in many ways. What I follow is name my method descriptive enough so that "what" is described. Add a comment on top of each method, which says why the method is needed. Name my variables reasonable enough so that "how" the goal is achieved becomes evident.

这篇关于代码中没有任何评论我被要求修复 - 没有任何一个的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！