Over many years of experience delivering successful projects, I’ve found one common element in each implementation. A clean, readable, and concise codebase is the key to effective collaboration and provides the highest quality value to the client.<\/p>\n\n\n\n
Code review is a crucial part of maintaining a high-quality code process. It is also a great way to share best practices and distribute knowledge among team members. At Appsilon, we treat code review as a must for every project. Read more about how we organize our work in Olga\u2019s blog post<\/a> on best practices recommended for all data science teams.<\/p>\n\n\n\n Having a well-established code review process does not change the fact that the developer is responsible for writing good, clean code! Pointing out all of the code\u2019s basic mistakes is painful, time-consuming, and distracts reviewers from going deep into code logic or improving the code\u2019s effectiveness.<\/p>\n\n\n\n Poorly written code can also harm team morale \u2013 code reviewers are frustrated while code creators might feel offended by a huge number of comments. That is why before sending the code to review, developers need to make sure that the code is as clean as possible. Also, note that there is not always a code reviewer that can come to the rescue. Sometimes you are on your own in a project. Even though you think the code is ok for you now, consider rereading it in a few months \u2013 you want it to be clear to avoid wasting your own time later on.<\/p>\n\n\n\n In this article, I summarize the most common mistakes to avoid and outline best practices to follow in programming in general. Follow these tips to speed up the code review iteration process and be a rockstar developer in your reviewer\u2019s eyes!<\/p>\n\n\n\n Adding comments to the code is a crucial developer skill. However, a more critical and harder to master skill is knowing when not<\/em> to add comments. Writing good comments is more of an art than a science. It requires a lot of experience, and you can write entire book chapters about it (e.g., here<\/a>). <\/p>\n\n\n\n There are few simple rules that you should follow, to, well, avoid comments about your comments:<\/p>\n\n\n\n Remember that the comments will stay in the code. If there is something that you would like to tell your reviewer, but only once, add a comment to Pull (Merge) Request and not to the code itself.<\/p>\n\n\n\n Example<\/strong>: I recently saw removing part of the code with a comment like: \u201cRemoved as the logic changed.\u201d Ok, good to know, but later that comment in the code looks odd and is redundant, as the reader no longer sees the removed code.<\/p>\n\n\n\n A common problem related to texts is the readability of string concatenations. What I encounter a lot is an overuse of the A better solution is to use Isn\u2019t it clearer without all those commas and quotation marks?<\/p>\n\n\n\n When dealing with many code blocks, it would be great to extract them to separate locations, e.g., to a .yml file<\/strong>. It makes both code and text blocks easier to read and maintain.<\/p>\n\n\n\n The last tip related to texts: one of the debugging techniques, often used in Shiny applications, is adding Loops are one of the programming building blocks and are a very powerful tool. Nevertheless, they can be computationally heavy and thus need to be used carefully. The rule of thumb that you should follow is: always double-check if looping is a good option. It is hardly a case that you need to loop over rows in Another common source of issues is looping over elements using the length of the object, e.g. Also, remember about the Even if you are working alone, you probably would like your program to run correctly on other machines. And how crucial it is when you are sharing the code with the team! To achieve this, never use absolute paths in your code, e.g. \u201c\/home\/marcin\/my_files\/old_projects\/september\/project_name\/file.txt\u201d. It won\u2019t be accessible for others. Note that any violation of folder structure will crash the code. <\/p>\n\n\n\n As you should already have a project for all coding work, you need to use paths related to the particular project \u2013 in this case; it will be \u201c.\/file.txt\u201d. What is more, I would suggest keeping all the paths as variables in a single place \u2013 so that renaming a file requires one change in code, not, e.g., twenty in six different files.<\/p>\n\n\n\n Sometimes your software needs to use some credentials or tokens, e.g., to a database or private repositories. You should never commit such secrets to the repository! Even if the entries are the same among the team. Usually, the good practice is to keep such values in Finally, let\u2019s focus on how you can improve your code. First of all, your code should be easily understandable and clean \u2013 even if you are working alone, when you come back to code after a while, it will make your life easier! <\/p>\n\n\n\n Use specific variable names, even if they seem to be lengthy \u2013 the rule of thumb is that you should be able to guess what is inside just by reading the name, so Do NOT abbreviate logical values Do not compare logical values using equations, like Make sure that your logic statements are correct. Check if you understand the difference in R between single and double logical operators<\/a>!<\/p>\n\n\n\n Good spacing is crucial for readability. Make sure that the rules are the same and agreed upon in the team. It will make it easier to follow each other\u2019s code. The simplest solution is to stand on the shoulders of giants and follow the tidyverse style guide<\/a>. <\/p>\n\n\n\n However, checking the style in every line during the review is quite inefficient, so make sure to introduce linter<\/strong> and styler<\/strong> in your development workflow, as presented in Olga\u2019s blog post<\/a>. This can be lifesaving! Recently we found an error in some legacy code that would have been automatically recognized by linter:<\/p>\n\n\n\n This does not return the sum of the elements as the author was expecting.<\/p>\n\n\n\n Speaking of variable names \u2013 this is known to be one of the hardest things in programming. Thus avoid it when it is unnecessary. Note that R functions return by default the last created element, so you can easily replace that:<\/p>\n\n\n\n With something shorter (and simpler, you don\u2019t need to think about names):<\/p>\n\n\n\n On the other hand, please DO use additional variables anytime you repeat some function call or calculation! It will make it computationally more effective and easier to be modified in the future. Remember to keep your code DRY \u2013 don\u2019t repeat yourself<\/a>. If you copy-paste some code, think twice whether it shouldn\u2019t be saved to a variable, done in a loop, or moved to a function. <\/p>\n\n\n\n And there you have it \u2013 five strategies to write clean R code and leave your code reviewer commentless. These five alone will ensure you\u2019re writing great-quality code that is easy to understand, even years down the road. Happy coding!<\/p>\n\n\n\n Visit Appsilon Data Science<\/a> for additional insight on this article: https:\/\/appsilon.com\/write-clean-r-code\/<\/a>.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":" This article showcases how clean and concise codebase is instrumental to achieve effective collaboration and provides insight on how to do so.<\/p>\n","protected":false},"author":602,"featured_media":80184,"comment_status":"closed","ping_status":"open","sticky":true,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":"","jetpack_post_was_ever_published":false},"categories":[339,343,338,341,351,344,342],"tags":[806,487,6591,508,1045],"contributors-categories":[13652],"class_list":["post-80143","post","type-post","status-publish","format-standard","has-post-thumbnail","category-data-science","category-programing-languages","category-ibkr-quant-news","category-quant-development","category-quant-europe","category-quant-regions","category-r-development","tag-data-science","tag-r","tag-rstats","tag-rstudio","tag-tidyverse","contributors-categories-appsilon"],"pp_statuses_selecting_workflow":false,"pp_workflow_action":"current","pp_status_selection":"publish","acf":[],"yoast_head":"\nAvoid Comments with Comments<\/h2>\n\n\n\n
trimws(.) # this function trims leading\/trailing white spaces<\/code>\u00a0\u2013 which is redundant. If the reader does not know what function\u00a0trimws<\/code>\u00a0is doing, it can be easily checked. A more robust comment here can be helpful, e.g.:\u00a0trimws(.) # TODO(Marcin Dubel): Trimming white spaces is crucial here due to database entries inconsistency; data needs to be cleaned.<\/code><\/li># TODO<\/code>\u00a0comment. Also, add some information to identify you as the author of this comment (to contact in case details are needed) and a brief explanation of why the following code is marked as TODO and not modified right away.<\/li>Strings<\/h2>\n\n\n\n
paste<\/code> function. Don\u2019t get me wrong; it is a great function when your string is simple, e.g. paste(\"My name is\", my_name)<\/code>, but for more complicated forms, it is hard to read: <\/p>\n\n\n\npaste(\"My name is\", my_name, \"and I live in\", my_city, \"developing in\", language, \"for over\", years_of_coding)<\/code><\/p>\n\n\n\nsprintf<\/code> functions or glue<\/code>, e.g. <\/p>\n\n\n\nglue(\u201cMy name is {my_name} and I live in {my_city} developing in {language} for over {years_of_coding}\u201d)<\/code><\/p>\n\n\n\nprint()<\/code> statements. Double-check whether the prints are not left in the code \u2013 this can be quite embarrassing during code review!<\/p>\n\n\n\nLoops<\/h2>\n\n\n\n
data.frame<\/code>: there should be a {dplyr}<\/code> function to deal with the problem more efficiently. <\/p>\n\n\n\nfor(i in 1:length(x)) ...<\/code>. But what if the length of x is zero! Yes, the loop will go another way for iterator values 1, 0. That is probably not your plan. Using seq_along<\/code> or seq_len<\/code> functions are much safer.<\/p>\n\n\n\napply<\/code> family of functions for looping. They are great (not to mention {purrr}<\/code> solutions)! Note that using sapply<\/code> might be commented by the reviewer as not stable \u2013 because this function chooses the type of the output itself! So sometimes it will be a list, sometimes a vector. Using vapply<\/code> is safer, as the programmer defines the expected output class.<\/p>\n\n\n\nCode Sharing<\/h2>\n\n\n\n
.Renviron<\/code> file as environmental variables that are loaded on start and the file itself is ignored in the repo. You can read more about it here<\/a>.<\/p>\n\n\n\nGood Programming Practices<\/h2>\n\n\n\n
table_cases_per_country<\/code> <\/em>is ok, but tbl1<\/code> is not. Avoid abbreviations. Lengthy is preferable to vague. Keep consistent style for object names (like camelCase or snake_case) agreed among the team members. <\/p>\n\n\n\nT<\/code> for TRUE<\/code> and F<\/code> for FALSE<\/code> \u2013 the code will work, but T<\/code> and F<\/code> are regular objects that can be overwritten while TRUE<\/code> and FALSE<\/code> are special values. <\/p>\n\n\n\nif(my_logical == TRUE)<\/code>. If you can compare to TRUE<\/code>, it means your value is already logical, so if(my_logical)<\/code> is enough! If you want to double-check that the value is TRUE<\/code> indeed (and not, e.g., NA<\/code>), you can use the isTRUE()<\/code> function.<\/p>\n\n\n\nsum_of_values <- first_element \n + second_element<\/code><\/pre>\n\n\n\nsum_elements <- function(first, second) {\n my_redundant_variable_name <- sum(first, second)\n return(my_redundant_variable_name)\n}<\/code><\/pre>\n\n\n\nsum_elements <- function(first, second) {\n sum(first, second)\n}<\/code><\/pre>\n\n\n\nConclusion<\/h2>\n\n\n\n