Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
Robert C. Martin offers in the fist chapter of his book 'Clean Code' several definitions of 'clean code' from differen well known software experts. How do you define clean code?
Easy to understand.
Easy to modify.
Easy to test.
Works correctly (Kent Beck's suggestion - very right).
These are the things that are important to me.
Code I'm not afraid to modify.
Code that doesn't require any comments to be easily understood.
Code which reads as close to a human language as possible. I mean it on all the levels: from syntax used, naming convention and alignment all the way to algorithms used, quality of comments and complexity of distribution of code between modules.
Simplest example for naming convention:
if (filename.contains("blah"))
versus
if (S_OK == strFN.find(0, "blah"))
Part of it depends on the environment/APIs used, but most of it is of course the responsibility of the developer
Point-free Haskell code. (Not really, though.)
Code in which the different modules or classes have clearly defined contracts, is a good start.
Code which doesn't break in multiple places when you make a single, seemingly insignificant change. It is also easy to follow the control path of the program.
Reusable code is also important. So not only important is the quality of the code, but where do you put.
Example, business logic into a Controller is a useless code
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 6 years ago.
Improve this question
I'm working in company with a big system with a messy code structure. I want to work with the right standards like polymorphism and design patterns.
But the code is such a mess and needs to be heavily refactored to do that. Also my current company gives me tasks, and if I have would heavily refactor, that will open many bugs in the system as it's not unit tested, of course.
What do you think? Should I work on the tasks on this bad structure to finish the work? Or tell them that we need rebuild many things (also they won't find a difference as the features already work now).
I think you need to start off with some unit tests.
Whilst doing the tasks you have been assigned, you could write some tests to test the code you are about to change, then you can refactor it.
Now you can start to write the code for your task, test-first.
If the code that is already there works, then refactoring is the best option. If it doesn't work, then a rewrite becomes possible.
Well...you need to work on multiple aspects.
First, learn best practices to write clean code (if you haven't yet) and request your team members the same. There are many useful books and online resources available for the same.
Second, do not expect that the situation will change overnight. Adopt "Boy scout rule" - it will gradually improve the code quality.
Third, start building your corpus of unit tests. Slowly, testable code will emerge out of the sea of untestable monolith.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
What is considered more appropriate style of writing conditional operators?
if(1){
puts("Hello")
}
or
if(1) puts("Hello")
Similar aspects of coding style are welcome too.
That's all depends on your preference, that's why we rarely see people code in the same style.. Moreover, it depends on which programming language you're using.. IMHO, the important thing in coding is code readability and comments, so when your BOSS asks other people to help or develop your code. He /she will spend the least amount of their time to understand your code..
If you ask specifically from your example above, I would prefer the first one.. Because in my OPINION, imagining the WHOLE code, that one will give better readability. HOWEVER, some people may argue that it will spend some of your time typing those brackets over and over..
As per the PSR standards any structure must always enclose the code in parentheses.
The body of each structure MUST be enclosed by braces. This standardizes how the structures look, and reduces the likelihood of introducing errors as new lines get added to the body.
from the official website
Please have a look under control structures section http://www.php-fig.org/psr/psr-2/
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I reviewed some professional code written in Ruby and found no comments. The code was reasonably clear to read but not self-documenting. Should I expect professionally written Ruby code to have comments? Or, is there some Ruby doctrine that comments are not considered essential?
This issue isn't unique to Ruby.
Code comments should be kept to an absolute minimum, because they are usually not updated when the code changes, and become more misleading than helpful.
As you have already suggested, the best code is self-documenting and requires no comments.
Edit: to clarify, if you cannot reduce the code to remove the complexity, you must provide comments. This is rare in my experience, and usually only applies when external components don't behave as you might expect.
Matz, the creator of Ruby, states his philosophy here and there: "The source code is the documentation. It even states all the bugs correctly." And he probably means that for comments as well. I think many people who don't comment in Ruby source code are following his words. Whether for you to follow him is up to you.
I have also read some Ruby introductory websites saying that, whenever you feel the necessity to comment, that is an indication that you should split that routine as in individual method, and name it as you were to comment that part.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
When you are rapid prototyping for features should you really worry about code quality & optimization?.
Looking back at the number of times a "prototype" ended up becoming the product, the answer would be yes.
Don't forget that you are not only prototyping the feature, you are also prototyping the design.
Yes to quality. No to optimization. This question should be community wiki.
I would focus on clarity.
If quality and optimisation are requirements for the prototype then yes. If not, then no. Just because you are doing rapid prototyping you don't abandon standard operating procedures like programming to a specification, using source code control, testing, etc. It is, perhaps, relatively unusual for high performance to be a requirement for a rapidly developed prototype, but that's another matter.
Yes. Focus on quality, clarity and simplicity AND comments to explain what its doing and why (don't bother with the how, unless its really complicated, that is what the code is for).
Just about all work we do here starts out as a what if? And if it works we continue with it.
We write comments that describe what should happen, before we write the code, then write the code to match the comments. Writing the comments first forces you to think about how you will structure it all. We've found that it prevents a lot of FALSE assumptions and actually makes development faster.
It also makes reusing this when you come back to it so much easier - you don't need to read the code and understand it, just read the comments. Don't go for the nonesense of self-documenting code, all that does is self-document the bugs, you've got nothing to check to see if the code matches the comments/documentation at all.
You can worry about optimization later - see this description of a huge win I got by changing from MFC CMaps to STL when working on a hobby project parsing some Apache log files. This was done after I had the initial concept working and only when it became apparent there was a problem with performance.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
Over the years, I've discovered that green-programmers tend to read the comments rather than the code to debug issues.
Does having one person document the other person's code (and vice-versa) with the code writer's approval increase code quality in the long term?
Is this a good idea?
aside: I'm looking for middle-ground between solo programming and pair programming in terms of budgeting.
People tend to look for the easiest solution to a problem. If there's an "human" description available, it's likely to be utilized before the reader delves into esoteric code. IOW, the comments will often be considered first, regardless of how green the programmer happens to be.
Comments should maintained as well as possible. Unfortunately, they can easily become stale (because they cannot be validated by the compiler). Therefore, they should be kept to a reasonable minimum, because, ultimately, the code itself is the only real comment that can be trusted.
As for who should write the comments, it depends at what level the comments are being written. For example, at higher levels the comments should describe the outside behavior of a module, and could be written by a larger group of people. Internally, however, the comments should explain the intent of the various chunks of code. That way, its easier for the reader to glean the mannerisms of the code. Those comments should be written by the coder.
I've found that "pair programming" works best when one person writes the code and the other one writes unit tests (working side by side so they can see what each other is doing). You can swap the roles around occasionally too.
You run a higher risk of misinterpreting algorithms if the original author does not document the code. In my opinion, the only thing more frustrating than inadequately documented code is incorrectly documented code.
You may wish to try this approach:
Perform code reviews with a developer that was not involved in the programming effort.
Have the review performed without the physical presence of the code's author. Just the reviewer, a copy of the code from source control, and written documentation.
If the reviewer can not reasonably understand the code without outside assistance, it is not adequately documented and should be given back to the author.
Repeat as necessary.
I find it works best when the helper does the broad scope thinking (i.e. What are we trying to accomplish) and the keyboard cowboy does the detail scope thinking. I don't think comments have anything to do with it.
I tend to write comment first and code immediately after that or at times or at times side by side. By the time I end up writing my comment the code becomes very clear in my mind (thanx to the fact of verbalizing my ideas while writing the comment). I don't like to comment the code which I haven't written. And whenever I come back to revise the code, first read the original comments, then think of new comments, write them and write the code side by side.