What should be the rules to write excellent code?

In summary, the book Code Complete by Steve McConnell is essential reading for anyone who writes code, as it covers many strategies for avoiding common mistakes and improving the quality of the codebase.
  • #1
pairofstrings
411
7
Hi.

I know few rules that let's me write great code:

1.
"don't pollute the global namespace" when I sit down to write JavaScript code.

2.
SOLID

3.
KISS

4.
Liskov's Open-Closed principle

Can someone help me complete the list of such rules?

Thanks!

Have a great day!
 
Technology news on Phys.org
  • #2
I think subject independent from programming language. Minimum, functional and structured programming.
 
  • #3
levadny said:
I think subject independent from programming language. Minimum, functional and structured programming.
I want to know the big words of programming so that I can look' em up on the internet and study about them.
 
  • #4
Test-driven development.

Code has to be written in such a way that each component of it can be tested independently with only a few lines of setup.
 
  • Like
Likes Stephenk53
  • #5
newjerseyrunner said:
Test-driven development.

Code has to be written in such a way that each component of it can be tested independently with only a few lines of setup.

Okay.
 
  • #7
pairofstrings said:
I want to know the big words of programming so that I can look' em up on the internet and study about them.
Ok. Then design patterns and software requirements.
 
  • #8
levadny said:
Ok. Then design patterns and software requirements.
Wow! Okay. Thanks!
 
  • Like
Likes levadny
  • #10
Give your variables very detailed and specific names, including iterators such as i, this alone has saved me days of work
 
  • Like
Likes atyy
  • #11
Documentation

Documentation

Documentation

(And reread post #10)
 
  • Like
Likes Borg
  • #12
Steve McConnell 'Code Complete 2' has all of the above and a lot more.

I think @Mark44 can verify that Microsoft had this book on its list of must reads - he was at the Redmond campus for years. I believe. His opinion of the book should count for a lot.
 
  • #13
Planning, documentation, experience - and an existing codebase to learn from...
 
  • #14
pairofstrings said:
3.
KISS
phinds said:
Documentation

Documentation

Documentation

(And reread post #10)
100% agree. I would also add that code should be written with two other things in mind.

1. Does your code follow coding and API standards that fall within the guidelines of the project?
2. Will programmers who have to work on your code later be able to understand it? (that includes yourself)

These come from two phrases that I often hear in the coding world that drive me crazy - job security and that will look good on my resume. Neither of these has the customer in mind. Those attitudes usually result in bloated, undocumented software in a language that nobody is familar with resulting in later programmers struggling to understand it and afraid to modify it.
 
  • #15
What is KISS?
 
  • #16
Keep It Simple, Stupid

The principle is best exemplified by the story of Johnson handing a team of design engineers a handful of tools, with the challenge that the jet aircraft they were designing must be repairable by an average mechanic in the field under combat conditions with only these tools. Hence, the "stupid" refers to the relationship between the way things break and the sophistication available to repair them.
Which goes back to my original statement about making things so complex and unusual that it can't easily be worked on by those who follow.
 
  • Like
Likes levadny
  • #17
When I was involved in Software Development, I always insisted on:
  1. A design document for the module (written in such a way that if it was inserted as comments in the source code, it would document the code)
  2. Do not publish any entry points to the code where you do not want to implement full parameter verification
  3. As we usually wrote in C: Run the code through lint until lint is satisfied.
 
  • #18
jim mcnamara said:
Steve McConnell 'Code Complete 2' has all of the above and a lot more.

I think @Mark44 can verify that Microsoft had this book on its list of must reads - he was at the Redmond campus for years. I believe. His opinion of the book should count for a lot.
Anyone who writes code and aspires to be a better programmer should have this book.
It was "Code Complete" at that time (about 2004 or so). Everyone in the Windows Division, about 7500 people, had to take a two-day class on strategies to protect the Windows OS from exploits such as buffer overruns and DOS (denial of service) attacks. Besides the class materials, each person received a copy of McConnell's book, which I still have. I didn't realize that this book is now in a second edition.
 
  • #19
Something I always make sure that I use:
Code:
-Wall -pedantic-errors -Werror
It sets the compiler to warn about everything that could possibly go wrong, not let you write non-standard code, and treat all warnings as compiler errors. Even before I go through QA, just setting these flags let's me find all sorts of stupid mistakes. Personally I like everything to be extremely explicit. Method takes a double? Better static_cast<double>() that float!
 
  • #20
Think, design, code.
Proper naming of variables, variable scope regarding context at hand, meaningful comments, use of efficient algorithms and efficient implementation and proper documentation are the simplest but unfortunately very often overlooked.
As your experience in programming grows stronger KISS principle changes (i.e. is adapted) accordingly.
Try to leverage the full power of the programming language, IDE, toolchain(s), libraries, frameworks, templates ... (the list goes on) - this also helps in not reinventing the wheel, but adapt and test properly.
When you're about to break some rule(s) justify extensively and if you have to, do it with enough parsimony.
 
Last edited:
  • #21
Avoid using 'goto' {label} type statements as if they were contaminated with black death pathogens.
 
  • #22
KISS - it means: let's do all very simple and reliable. Yes?
 
  • #23
rootone said:
Avoid using 'goto' {label} type statements as if they were contaminated with black death pathogens.
While I agree this is good advice for beginners, there are legitimate uses for goto's for those who are more advanced. In another thread (https://www.physicsforums.com/threa...number-is-a-prime-number.941151/#post-5951715) I posted the following:
Mark44 said:
From "Code Complete," by Steve McConnell, p. 348, in a section titled "The Argument for gotos":
The goto is useful in a routine that allocates resources, performs operations on those resources, and then deallocates the resources. With a goto, you can clean up in one section of code. The goto reduces the likelihood of your forgetting to deallocate the resources in each place you detect an error.

In some cases, the goto can result in faster and smaller code. Knuth's 1974 article cited a few cases in which the goto produced a legitimate gain.

Good programming doesn't mean eliminating gotos. Methodical decomposition, refinement, and selection of control structures automatically lead to goto-free programs in most cases. Achieving gotoless code is not the aim, but the outcome, and putting focus on avoiding gotos isn't helpful.

Two decades' worth of research with gotos has failed to demonstrate their harmfulness. In a survey of the literature, B.A. Sheil concluded that unrealitic test conditions, poor data analysis, and inconclusive results failed to support the claim of Shneiderman and others that the number of bugs in code was proportional to the number of gotos (1981)...
In fairness, McConnell also has a section titled "The Argument Against gotos".
 
  • #24
I agree there are limited situations where they are useful.
For a beginner though they should definitely be avoided because it looks like an easy way of making stuff work.
The resulting code might actually work, but would be difficult for anyone else other than the original coder to make sense of.
Code spaghetti.
 
  • #25
GOTO is an unworthy sidetrack in this thread.

Compsi guru Edsger W. Dijkstra started it; but he complained only about excessive use of GOTO and spaghetti code. An even more luminary compsci guy Donald Knuth wrote "Structured Programming with go to Statements" It is blown out of proportion.

IMO, this thread is about ideas much more important than GOTO.
 
  • Like
Likes NTL2009
  • #26
anorlunda said:
An even more luminary compsci guy Donald Knuth wrote "Structured Programming with go to Statements"
Here's a working link to the Knuth paper --
http://sbel.wisc.edu/Courses/ME964/Literature/knuthProgramming1974.pdf
The one that anorlunda gave results in a 403 Forbidden HTTP error.
 
  • Like
Likes jim mcnamara and anorlunda
  • #27
Principle of least astonishment (POLA)
 
  • #28
Coelum said:
Principle of least astonishment (POLA)
Something like this?
CodeReviewQuality_clean.jpg
 

Attachments

  • CodeReviewQuality_clean.jpg
    CodeReviewQuality_clean.jpg
    19.1 KB · Views: 392
  • Like
Likes berkeman, QuantumQuest, FactChecker and 2 others
  • #29
rootone said:
I agree there are limited situations where they are useful.
For a beginner though they should definitely be avoided because it looks like an easy way of making stuff work.
The resulting code might actually work, but would be difficult for anyone else other than the original coder to make sense of.
Code spaghetti.
A GOTO does not necessarily infer spaghetti code. A short jump with a GOTO can make code simpler and easier to read than the logic required to avoid it.

What is a BREAK statement? It is really just A "GOTO the end of this code segment" statement, yet I don't hear people call for the end of the break statement.

Yes, GOTO has been abused, but that does not mean that we need to avoid it, it just means that we should use it properly like any tool.
 
  • #31
Document, document, document.
Read through the requirement
Identify testable statements
Use a design methodology relevant to the task/project
Use a recognised standard for documentation and design toolset
Identify methods/objects at the design stage
Use a programming language relevant to the task.
Wherever possible reuse known working classes if OOD/OOP
or working modules if procedural design.
Ensure the smallest components are easily testable, build up a library of components that could be reused later
Test each class/procedure from the bottom up, increasing complexity as you go, ensuring that the system requirements continue to be met
Test
Test
Test
The aim of the exercise is to obtain a software system that is fit for purpose and does what is required.
 
  • Like
Likes Svein

1. What is the most important rule for writing excellent code?

The most important rule for writing excellent code is to keep it simple and easy to understand. This means using clear and concise syntax, avoiding unnecessary complexity, and following best practices and coding conventions.

2. How can I make sure my code is efficient and optimized?

To ensure that your code is efficient and optimized, you should focus on writing clean and organized code, avoiding redundant or unnecessary operations, and regularly testing and debugging your code for any performance issues.

3. What role do comments play in writing excellent code?

Comments are an essential part of writing excellent code as they help to explain the purpose and functionality of different sections of code. They also make it easier for other developers to understand and maintain your code in the future.

4. Is it important to follow coding standards and guidelines?

Yes, following coding standards and guidelines is crucial for writing excellent code. These standards help to ensure consistency and readability in your code, making it easier for others to understand and work with.

5. How can I improve my coding skills and write better code?

The best way to improve your coding skills and write better code is to practice regularly and continuously learn new techniques and technologies. You can also seek feedback from other experienced developers and participate in coding challenges and projects to enhance your skills.

Similar threads

  • Programming and Computer Science
Replies
4
Views
700
  • Programming and Computer Science
Replies
3
Views
2K
  • Programming and Computer Science
Replies
32
Views
2K
  • Programming and Computer Science
2
Replies
49
Views
3K
  • Programming and Computer Science
Replies
9
Views
3K
  • Programming and Computer Science
Replies
6
Views
977
  • Programming and Computer Science
2
Replies
47
Views
4K
Replies
10
Views
896
  • STEM Academic Advising
Replies
11
Views
1K
  • Engineering and Comp Sci Homework Help
Replies
7
Views
1K
Back
Top