Consciously Code

Category: Collaboration and Communication

Best practices for working with other developers and communicating effectively.

Applying Agile Principles in Your Day-to-day Can Help You Become a More Conscious Software Developer
In today’s fast-paced and ever-changing world of software development, it’s more important than ever to be a conscious developer. Being a conscious developer means being aware of the impact your work has on others, constantly improving your skills and processes, and working collaboratively with your team to achieve shared goals. In essence, a conscious developer is aware that the choices they make in their code have an impact beyond just the application.

One way to become a more conscious developer is by applying agile principles in your day-to-day work. Agile principles emphasize collaboration, adaptability, and continuous improvement, all of which can help you become more aware of your choices and their effects, ultimately improving the quality of your work.

In this blog post, we’ll explore how agile principles can help you become a more conscious software developer and provide practical examples of how you can incorporate these principles into your personal development process. Whether you’re a seasoned developer or just starting out, this post will provide valuable insights into how you can become a more effective and conscious member of your development team.

Applying Agile: Collaboration

Collaboration is a fundamental aspect of agile principles. In an agile team, everyone works together towards a shared goal, communicating regularly to ensure that everyone remains aligned on the goal. By working collaboratively, team members can identify potential issues and blockers early on and take appropriate action quickly to realize rapid progress. This emphasis on collaboration can make you more conscious of your role as a software developer.

Photo by Canva Studio on Pexels.com

When working collaboratively, you become more aware of how your work impacts others. You gain an understanding of the dependencies between different parts of your codebase and how changes to one area can affect a team member. This awareness can help you make more informed decisions as you work and ensure that you’re not introducing unnecessary bugs or breaking other parts of the system.

Furthermore, collaboration can help you become more empathetic towards your colleagues. By working and communicating closely with them, you gain an appreciation for the challenges and constraints that they face. This understanding can help you be more considerate of other team members’ needs and concerns, leading to better collaboration and more effective outcomes.

Overall, collaboration is a powerful tool for becoming a more conscious software developer. By engaging closely with your team, you can become more aware of your impact on others and develop a more empathetic and effective approach to your work.

Applying Agile: Adaptability

Another key agile principle is adaptability. In an agile environment, change is expected and embraced. Rather than following a rigid plan, teams continuously assess their progress and adjust their approach as needed to achieve their goals. Applying agile principles like adaptability can help you become more conscious of your own limitations and help you improve your personal process.

By acknowledging your own limitations, you can become more receptive to feedback and open to learning from others. This willingness to learn can help you become a more effective developer and improve the quality of your work. Additionally, being adaptable can help you identify areas where you can improve your development process.

Photo by Suzy Hazelwood on Pexels.com

For example, at one point in my career, I was juggling about six different projects at once. Things quickly got really hard to manage with all the different requirements and tasks assigned to me. It was at that point that I took a step back. I analyzed my situation and realized that I could do better. I decided to manage my own backlog by running a mini-sprint each day.

So, I began to hold a mini-sprint planning meeting with myself each morning. Here I would analyze my backlog and tackle the most important items on it. I then laser focus my attention on that small set of tasks for the day. At the end of the day, I’d hold a mini-retrospective with myself and prepare my backlog for the next day.

It was amazing to me how this seemingly simple action changed my productivity. I was able to excel in all of those projects, producing high-quality work on time and on schedule. I’ve been executing mini-sprints for myself ever since!

In summary, adaptability is a key component of becoming a conscious software developer. By embracing change and being open to learning, you can overcome your limitations and identify areas for improvement.

Applying Agile: Continuous Improvement

Continuous improvement is another essential aspect of the conscious software developer. Rather than viewing development as a one-time effort, teams in an agile environment strive to continuously refine and improve their work. This focus on continuous improvement can help you become more conscious of your own growth as a developer.

Photo by Bruno Bueno on Pexels.com

By constantly seeking to improve your skills and processes, you can become more effective at your job and deliver higher-quality software. This may involve learning new programming languages or frameworks, experimenting with new development techniques (such as design patterns!), or simply seeking feedback from your colleagues. By seeking out new opportunities for growth, you can stay up-to-date with the latest industry trends and ensure that your skills remain relevant.

Furthermore, continuous improvement can help you identify areas where you can improve your development process. By regularly assessing your work and soliciting feedback from your colleagues, you can identify areas where you may be able to streamline your workflow or improve your code quality. Collaboration and continuous improvement go hand in hand. This focus on continuous improvement can help you create more robust, efficient, and effective software that meets the needs of your users.

Honestly, continuous improvement is probably the most critical component of becoming a conscious software developer. By constantly seeking to improve your skills and processes, you can become more effective at your job, deliver higher-quality software, and ensure that your skills remain relevant in an ever-changing industry.

Conclusion

In conclusion, agile principles can be a powerful tool for becoming a more conscious software developer. By emphasizing collaboration, adaptability, and continuous improvement, agile principles can help you become more aware of your impact on others, identify areas for improvement, and create more efficient and effective software. Whether you’re a seasoned developer or just starting out, applying agile principles into your personal development process can help you become a more effective and conscious member of your team. So why not give it a try and see how it can improve your development workflow and outcomes?

Additional Resources
- Agile Manifesto: The official website of the Agile Manifesto provides an overview of agile principles and values. You can apply each of these to your own day-to-day life as a developer.
- Scrum.org: Scrum is a popular agile framework that is used in many business settings. Scrum.org provides free resources such as webinars, case studies, and articles about applying Scrum in different contexts. It can provide valuable insight into applying agile principles to your daily routine. Read more on their blog and resources pages.
- Agile Alliance: A non-profit organization that provides resources for people who want to learn about agile principles and practices. The website includes articles, webinars, podcasts, and other resources that can help you apply agile principles to your personal development. Pay close attention to the Agile Essentials portion of their site.
- The Lean Startup: The Lean Startup methodology is based on agile principles and can be applied to personal development. The website provides free resources such as articles and videos about how to apply lean principles in your work.
- Leading Agile: LeadingAgile.com is a consulting and training company focused on helping organizations adopt agile principles and practices. They provide a range of services including coaching, training, and transformation services for enterprise-level agile adoption. They offer a Personal Agility Canvas that can help you visualize your personal goals and priorities and how you add value to your organization.
March 7, 2023
Communication Skills and Their Vital Role in Software Development
Software development is not just about writing code and designing algorithms. It is a team effort that involves constant communication and collaboration between team members. Communication skills are therefore an essential part of a software developer’s toolkit — especially for conscious developers. Effective communication can help teams work together smoothly, solve problems more efficiently, and ultimately deliver high-quality software products. In contrast, poor communication can lead to project delays, misunderstandings, and even failure.

In this blog post, we will explore the vital role of communication skills in software development. We will delve into the different types of communication skills, the negative impact of poor communication, and how to improve how we communicate. We will also discuss how effective communication can enhance team collaboration and how it is crucial in agile methodologies.

If you are a conscious software developer looking to improve your skills, then this post is for you. We will provide you with insights and tips on how to become a better communicator and a more effective member of your team. So, let’s dive in!

What are communication skills?

Communication skills refer to the ability to exchange information, ideas, and thoughts effectively. It includes not only verbal communication but also non-verbal communication such as body language, facial expressions, and tone of voice. As a conscious developer, effective communication is critical because you must convey technical information to not only your team, but various stakeholders such as project managers and clients as well.

Photo by fauxels on Pexels.com

Listening

This is a skill that provides the basis for all communication. In my honest opinion, the best listeners are the absolute best communicators. The ability to actively listen and understand what others are saying is an essential skill that helps in comprehending the requirements of the project, identifying the problems, and building a rapport with team members.

Speaking

Speaking begins with listening because you cannot convey information clearly, concisely, and confidently if you don’t have an understanding of your audience or what your requirements are. This skill is essential when communicating with stakeholders, presenting technical information, and giving status updates.

Writing

Effective writers are also effective listeners. Writing is the ability to express ideas and information in written form. It includes writing emails, documenting code, creating user manuals, and other written materials. While writing may not be the most exciting part of good software development, it remains an essential one.

Relating

Relatability is a natural byproduct of being a strong listener. It is the ability to interact and build relationships with others effectively. This includes skills such as empathy, emotional intelligence, and teamwork which are vital for creating a positive and productive work environment.

What is the impact of poor communication?

Poor communication skills can have a significant impact on software development projects and teams. It can lead to misunderstandings, delays, and project failures, as well as isolated, ineffective people. Here are some examples of how poor communication can have a negative impact:
1. Misunderstandings: Misunderstandings can occur when team members do not communicate effectively. For example, a developer may misunderstand the requirements of a project, leading to incorrect assumptions and time spent coding the wrong solution. This results in project delays and rework.
2. Delays: When team members are not aware of the status of the project or the tasks assigned to them, delays are the natural result. This can lead to confusion and duplication of effort, as well as frustration from customers and other stakeholders.
3. Conflict: Poor communication can lead to conflict among team members. For example, if a team member feels that their ideas or concerns are not being heard, they may become resentful, leading to a negative and toxic work environment.
4. Project Failure: Poor communication can ultimately lead to project failure. If your team is not communicating effectively, it can result in a product that does not meet the requirements or expectations of the client.
In summary, poor communication can lead to misunderstandings, delays, conflict, and ultimately project failure. It is therefore essential for conscious developers to strengthen and improve their communication skills.

How can communication skills be improved?

Effective communication is a skill that can be improved with practice and training. It comes down to becoming aware of where you fall short, so you can focus your effort and learning there.

Photo by Moose Photos on Pexels.com

Active Listening

This most essential communication skill involves listening attentively and asking questions to clarify understanding. To improve this skill, focus on being present in the moment, maintaining eye contact, and avoiding distractions. You can truly listen to just one voice at a time. So put your phone down when talking with a colleague. Listen to your direct report completely before thinking about your own response. Give your full attention to the meeting your presence was requested to be in.

Regular Communication and Feedback

Regular communication and feedback can help in improving communication skills because it helps develop the necessary awareness to take action. Strive to communicate regularly with your team members and project stakeholders, providing updates, and seeking feedback to ensure everyone is on the same page.

Training and Development Opportunities

Take advantage of training and development opportunities to improve your communication skills. This can include attending communication workshops, reading books on effective communication, and seeking mentorship from experienced developers. There are a few additional resources at the end of this post to help you get started.

Empathy and Understanding

Empathy and understanding are crucial for effective communication. Strive to understand the perspective of others, considering their needs and expectations. This can help in building better relationships with team members and project stakeholders.

By empathizing with team members, you can better understand their needs, motivations, and challenges. This understanding will help you work more effectively with your team members, creating a more collaborative and supportive work environment.

Empathy will also help you understand the needs and perspectives of stakeholders and customers. This helps you create software products that meet the needs of your users and deliver more value to the business.

By improving communication skills, you can ensure that everyone is on the same page, avoid misunderstandings, and ultimately deliver high-quality software products. But more importantly than even that, you build strong relationships in your team. And strong teams are successful teams.

How do communication skills work in team collaboration?

Photo by Pixabay on Pexels.com

Effective communication skills are essential for team collaboration in software development. When a team exhibits good communication skills, all communication channels are open and considered safe for people to use. Here are some ways communication skills impact team collaboration:
1. Building Trust: Effective communication skills help build trust among team members, which is crucial for successful collaboration. Trust allows team members to work together, share ideas, and make decisions collectively.
2. Resolving Conflicts: Conflicts are inevitable in any team. Effective communication skills help resolve conflicts by ensuring that team members can express their concerns and work towards a mutually beneficial solution.
3. Sharing Knowledge: Effective communication skills allow team members to share knowledge, ideas, and expertise. This sharing of knowledge can lead to better decision-making and ultimately result in higher quality software products.
4. Building Rapport: Effective communication skills allow team members to build rapport, which is crucial for creating a positive and productive work environment. A positive work environment leads to higher job satisfaction, which results in better performance and ultimately higher quality software products.
Effective communication skills are crucial for team collaboration in software development. With a constructive communication culture, team members feel safe to share their thoughts, successes, ideas, and concerns. This enables the team to establish trust, resolve conflicts, share knowledge, and build rapport, ultimately resulting in an extremely high-performant team.

Conclusion

In conclusion, effective communication skills are crucial for software developers to become conscious developers who can build high-quality software products. These skills are essential for team collaboration, agile methodologies, and project success. Software developers should strive to improve their communication skills by actively listening, seeking regular feedback, taking advantage of training and development opportunities, and building empathy and understanding. Open communication channels are critical for team collaboration, trust building, conflict resolution, better performance, and job satisfaction. By becoming conscious developers who prioritize effective communication, software developers can ensure the success of their projects and contribute more value to their team.

I challenge you to start today to begin to improve your communication skills. Start by making a conscious effort to become aware of where you fall short; then make a plan to learn and grow!

Additional Resources
- EQ Applied: Justin provides some great resources here to improve your overall emotional intelligence, or EQ. His website focuses on EQ and how it can be applied to work and life. The site provides resources, articles, and courses to help individuals develop their emotional intelligence, improve their communication skills, and build better relationships.
- Three Key Communication Skills That Software Developers Must Master: This article by Kailyn Nelson highlights three key communication skills that software developers should cultivate: active listening, empathy, and clear articulation. It explains how these skills can help developers build better relationships with team members, stakeholders, and customers, leading to more successful projects and better software products.
- 5 Ways to Improve Communication Skills for Software Developers: This article by Borys Nikolenko outlines five essential ways for software developers to improve their communication skills, including active listening, asking questions, practicing empathy, using appropriate language, and seeking feedback. The article emphasizes the importance of effective communication skills for successful software development and provides practical tips for developers to implement in their work.
March 4, 2023
Why Writing Good Comments Makes You a Great Developer
Commented, xkcd.com #156

When you think of a great developer, I’m sure someone who writes good comments often is not at the top of the list. However, writing good comments is one of the most important skills a developer can have. Good comments not only help you understand your code better, but they also make it easier for others to read and work with. In this blog post, we’ll look at why writing good comments makes you a great developer and some tips for improving your commenting style. Because if you are mindful in your commenting, it is an indication that you are mindful in your coding!

Comments Should Be Present

Well-written code comments are like a good road map. They provide clear direction and helpful information that can make working with code much easier. Good code comments can be incredibly useful, providing critical insights and details that might otherwise be easy to miss. Think of them as important signposts along the way that can save a developer hours of debugging.

Here is an example of something I came across recently that was not obvious. I was writing a CMake function to add unit tests using CTest. I was passing in a CMake string as my “TEST_COMMAND” variable. When I would call add_test with that variable as the value for the COMMAND option the test would fail to run properly, especially if the command took command line arguments! After spending some time digging I learned that the COMMAND option to add_test should be a CMake list rather than a string for the arguments to be passed properly.

I commented my CMakeLists.txt as such to ensure that was clear to the reader.
```
# TRICKY: Change the command string to a CMake list for use in add_test()
string(REPLACE " " ";" TEST_LIST ${TEST_COMMAND})
add_test(NAME ${TEST_NAME} COMMAND ${TEST_LIST})
Code language: CMake (cmake)
```
Without the “TRICKY” comment, a maintainer of this code may look at this and see potential for an optimization, removing the conversion, and then they would be searching for solutions to the same problem I had already solved.

Comments Should Use Proper Spelling, Casing, Grammar, and Full Sentences

Good code comments are spelled correctly. They are also properly cased. This attention to detail shows that the programmer cares about their work.

Take a look at the two examples of code below. Which one would you say is written by a mindful developer? Which one would you rather work to maintain?
// copute ac/a+c double prodOverSum(int a, double c) {// git the nmeratr for the rtn double n = (double)a * c; // get the denomination for the value int d = a + (int)c; /// comput and return the quotient return n / (double)d; }Code language: C++ (cpp)
// Compute the product over sum for // the provided values, a and c. // (A * C) // X = --------- // (A + C) double prodOverSum(int a, double c) { double prod = (double)a * c; int sum = a + (int)c; // Cast sum to a double to ensure // the compiler does not promote prod // to an integer and perform integer // division return prod / (double)sum; }Code language: C++ (cpp)
It’s clear that the programmer cares about their craft when they put so much effort into writing clear, readable comments. It would be almost impossible to maintain this level of detail by chance, which makes me believe it is intentional as opposed just being accidental! That gives me confidence that the code itself is well-written, properly tested, and ready for use.

When writing comments, it is important to use full sentences with proper grammar as well. This will help ensure that your comments are clear and easy to understand. Additionally, using proper grammar will help to give your comments a more professional appearance.

Comments Should Be Smartly Formatted

Comments are meant to convey a message about the surrounding code to the developer. Sometimes information is best conveyed in a particular format. So, when commenting your code, ensure that your comment is formatted in such a way that conveys your message as clearly and concisely as possible.

Code formatters can help and hinder this. If your comments require lots of horizontal scrolling to read, then consider breaking them into multiple lines or rewording to be more concise! However, sometimes a new line in the middle of your documentation is undesirable and you will need to instruct your formatter to leave it alone by wrapping with “control comments”.

For example, consider this method. If I was to line up all the columns in the table neatly, this would make for some very long lines of text. Most formatters would break these lines into multiple ones. Instead, make judicious use of white space to get the message across to the reader. If you have to use multiple lines, you decide where those line breaks are – don’t leave it up to your formatter!
```
void Quaternion2DCM(const double * const q, double * const dcm)
{
  // Don't do this! Your formatter will either add new lines or ignore this
  // if you add protection blocks around the table, making for really long 
  // lines that are harder to read.
  // To compute the DCM given a quaternion, the following definition is used
  //       +-------------------------------------------------------------------------------------------+
  //       | (q4^2 + q1^2 - q2^2 - q3^2)    2*(q1q2 + q3q4)                2*(q1q3 - q2q4)             |
  // dcm = | 2*(q1q2 - q3q4)                (q4^2 - q1^2 + q2^2 - q3^2)    2*(q2q3 - q1q4)             |
  //       | 2*(q1q3 + q2q4)                2*(q2q3 − q1q4)                (q4^2 - q1^2 - q2^2 + q3^2) |
  //       +-------------------------------------------------------------------------------------------+
  // clang-format off
  // Adapted from https://www.vectornav.com/resources/inertial-navigation-primer/math-fundamentals/math-attitudetran
  // clang-format on
  dcm[0] = q[3]*q[3] + q[0]*q[0] - q[1]*q[1] - q[2]*q[2];
  dcm[1] = 2*(q[0]*q[1] + q[2]*q[3]);
...
  dcm[7] = 2*(q[1]*q[2] - q[0]*q[3]);
  dcm[8] = q[3]*q[3] - q[0]*q[0] - q[1]*q[1] + q[2]*q[2];
}
Code language: C++ (cpp)
```
```
void Quaternion2DCM(const double * const q, double * const dcm)
{
  // Instead, you can do this - just simple white space, still very readable
  // by the user and it fits on a single line!
  // To compute the DCM given a quaternion, the following definition is used
  //       +-------------------------------------------------------------------+
  //       | (q4^2 + q1^2 - q2^2 - q3^2)    2*(q1q2 + q3q4)    2*(q1q3 - q2q4) |
  // dcm = | 2*(q1q2 - q3q4)    (q4^2 - q1^2 + q2^2 - q3^2)    2*(q2q3 - q1q4) |
  //       | 2*(q1q3 + q2q4)    2*(q2q3 − q1q4)    (q4^2 - q1^2 - q2^2 + q3^2) |
  //       +-------------------------------------------------------------------+
  // Adapted from https://www.vectornav.com/resources/inertial-navigation-primer/math-fundamentals/math-attitudetran
  dcm[0] = q[3]*q[3] + q[0]*q[0] - q[1]*q[1] - q[2]*q[2];
  dcm[1] = 2*(q[0]*q[1] + q[2]*q[3]);
...
  dcm[7] = 2*(q[1]*q[2] - q[0]*q[3]);
  dcm[8] = q[3]*q[3] - q[0]*q[0] - q[1]*q[1] + q[2]*q[2];
}
Code language: C++ (cpp)
```
How Much Should I Comment?

Good code will be somewhat self-documenting, but there is always a limit. For example, the method below is so obvious I don’t really need to comment on it, do I?
```
int sum(const int a, const int b)
{
  return a + b;
}
Code language: C++ (cpp)
```
However, for something more involved, comments can clarify a lot of things for the developer and can link them to more information, as in the example of the Quaternion2DCM method described above.

So, then, how do you define what is obvious? For me, I think in terms of my average user and/or maintainer. What sort of things do I expect them to understand? What about more junior software engineers who may need to work in this code? Basic math and logic knowledge seems okay. Syntax is a given; even more advanced syntax, such as lambdas or function pointers, I would expect them to be able to read. However, anything beyond that typically indicates the need for a detailed comment that explains things.

It also helps me to think in terms of what will help me understand this design decision tomorrow, or 6 months from now, or even a year from now. Maybe it is obvious to me now what that this conditional with multiple clauses means and why it is this way in the design, but I’ll likely forget tomorrow and want to refactor.

Comments In Your IDE

To make working with comments easier, look for ways to get your IDE to help you! I use VS Code for nearly all my coding right now and I found the extension Better Comments to be extremely helpful.

Image Credit: Better Comments Plugin

With this plugin I can add additional formatting and mark comments specifically. For example, in my code I tend to leave myself reminders using TODO and will often prioritize those TODO comments using regular TODO and prefixing with ‘*’ and ‘!’.
```
// ! TODO: This is an important TODO that needs to be taken care of immediately
// * TODO: This is an important TODO that should be taken care of soon
// TODO: This is a TODO that should be taken care of eventuallyCode language: C++ (cpp)
```
With this plugin my comments are color-coded for me, making it easy to see what needs to be done first.

In the end, your code is the reflection of you, so it only makes sense that your commenting reflects how much care and attention to detail there really is in what’s being written. If poor commenting sends a message on its own then people will be able to tell if they need more time before investing any kind of faith into your code—or even worse, they’ll just move onto another potentially better implementation!

What do you think? What makes a good comment in your book? Let us know in the comments below!
June 8, 2022
6 Tips for an Absolutely Perfect Little Code Review
Code reviews are an important part of the software development process. They help ensure that code meets certain standards and best practices, and they can also help improve code quality by catching errors early on. However, code reviews can also be a source of frustration for developers if they’re not done correctly.

Image Credit Manu Cornet @ Bonker’s World

As a code reviewer, your job is to help make the code better. This means providing clear and concise feedback that helps the developer understand what works well and what needs improvement. A mindful, conscious approach to code reviews can yield incredible dividends down the road as you build not only a solid, reliable codebase; but strong relationships of trust with your fellow contributors.

Here are some initial guidelines or best practices for performing a great code review:
- Read the code thoroughly before commenting. This will help you get a better understanding of what the code is supposed to do and how it works.
- Be specific in your comments. If there’s something you don’t like, explain why. Simply saying “this doesn’t look right” or “I don’t like this” isn’t helpful.
- Offer suggestions for how to improve the code. If you have a suggestion for how something could be done differently, provide details about the suggestion and even some links and other material to back it up.
- Be respectful. Remember that the code you’re reviewing is someone else’s work. Criticizing someone’s work can be difficult to hear, so try to be constructive with your feedback. Respectful, polite, positive feedback will go a long way in making code review a positive experience for everyone involved.
- Thank the developer for their work. Code reviews can be tough, so make sure to thank the developer for their efforts.
Following these practices will help ensure that code reviews are a positive experience for both you and the developer whose code you’re reviewing.

In addition to these, here are a few specifics I look for when performing a code review:

“146/365 square peg into a round hole” by rosipaw is licensed under CC BY-NC-SA 2.0.

0. Does the code actually solve the problem at hand?

Sometimes when I get into code reviews I forget to check if the written software meets the requirements set forth. As you do your initial read-through of the code, this should be your primary focus. If the code does not solve the problem properly or flat out misses the mark, the rest of the code review is pointless as much of it will likely be rewritten. There’s nothing worse than spending an hour reviewing code only to find out later that it doesn’t work. So save yourself the headache and make sure the code compiles and does what it’s supposed to do before you start.

1. Is the code well written and easy to read? Does the code adhere to the company’s code style guide?

It’s important to format code consistently so that code reviews are easier to perform. Utilizing standard tools to format code can help ensure that code is formatted consistently. Additionally, the code should be reviewed according to a standard set of guidelines. Many formatters will format the code per a chosen (or configured) style, handling all the white space for you. Other stylistic aspects to look for are naming conventions on variables and functions, the casing of names, and proper usage of standard types.

Structural and organizational standards are important as well. For example, checking for the use of global variables, const-correctness, file name conventions, etc. are all things to look out for and address at the time of the code review.

“Last of the color coding” by juhansonin is licensed under CC BY 2.0.

2. Is the code well organized?

Well-organized code is very subjective, but it is still something to look at. Is the structure easy to follow? As a potential maintainer of this code, are you able to find declarations and definitions where you would expect them? Is the module part of one monolithic file or broken down into digestible pieces that are built together?

In addition, be sure to look out for adequate commenting in the code. Comments should explain what the code does, why it does it, and how it works, especially to explain anything tricky or out of the ordinary. Be on the lookout for spelling errors as well because a well-commented codebase rife with spelling errors looks unprofessional.

3. Is the code covered by tests? Are all edge cases covered? What about integration testing?

Anytime a new module is submitted for review, one of the first things I look for are unit tests. Without a unit test, I almost always reject the merge/pull request because I know that at some point down the road a small, insignificant change will lead to a broken module that cascades through countless applications. A simple unit test that checks the basic functionality of the module, striving for 100% coverage, can save so much time and money in the long term. Edge cases are tricky, but if you think outside the box and ensure that the unit test checks even the “impossible” scenarios, you’ll be in good shape.

Integration tests are a different matter. In my line of work, integration testing must be done with hardware-in-the-loop and that quickly becomes cost-prohibitive. However, as integration tests are developed and a test procedure is in place, any and all integration tests must be performed before a change will be accepted; especially if the integration test was modified in the change!

4. Are there any code smells?

Common code smells I look out for are:
- Code bloat: long functions (> 100 lines), huge classes
- Dispensable code: duplication (what I look for the most), stray comments, unused classes, dead code, etc.
- Complexity: cyclomatic complexity greater than 7 for a function is prime fodder for refactoring
- Large switch statements: could you refactor to polymorphic classes and let the type decide what to do?
Many other smells exist – too many to check in detail with each code review. For a great deep-dive I refer you to the Refactoring Guru. Many static analysis tools will check for various code smells for you, so be sure to check the reports from your tools.

The presence of a code smell does not mean that the code must be changed. In some cases, a refactor would lead to more complex or confusing code. However, checking for various smells and flagging them can lead to discussions with the developer and produce a much better product in the end!

5. Would you be happy to maintain this code yourself?

One of the last things I check for during a code review is whether I would be okay to maintain this code on my own in the future. If the answer is no, then that turns into specific feedback to the developer on why that is the case. Maybe the structure is unclear, the general approach is questionable, or there are so many smells that it makes me nervous. Typically in cases like this, I find it best to give the developer a call (or talk with them in person) and discuss my misgivings. An open, honest discussion about the potential issues often leads to added clarity for me (and it’s no longer an issue) or added clarity for them and they can go fix the problem.

These are just a few of the specific things I look for, but following the practices above will help make code reviews a positive experience for everyone involved. What are some best practices or tips you have found to lead to a good code review? Thanks for reading!
May 18, 2022