[{"data":1,"prerenderedAt":399},["ShallowReactive",2],{"/blog/code-clarity":3},{"id":4,"title":5,"article_last_modified_time":6,"article_published_time":7,"body":8,"description":18,"extension":390,"is_published":391,"meta":392,"navigation":391,"ogImage":393,"path":394,"rawbody":395,"seo":396,"stem":397,"tags":393,"__hash__":398},"blog/blog/code-clarity.md","Code Clarity","2025-04-23T21:21:14+0200","2025-04-20T10:41:34+0200",{"type":9,"value":10,"toc":383},"minimark",[11,15,19,22,27,30,34,56,75,79,85,88,95,103,107,110,128,138,247,256,263,316,319,323,329,332,335,340,343,348,356,361,368,373,376,379],[12,13,5],"h1",{"id":14},"code-clarity",[16,17,18],"p",{},"How good practices around your code can improve your workflow.",[16,20,21],{},"I want to share some of the conventions I try to follow in my projects, and why I use them in this way.",[23,24,26],"h2",{"id":25},"introduction","Introduction",[16,28,29],{},"These are some practices that improve oversight and collaboration in projects for me. This is not about code style itself: there are a lot of books out there about that, written by way smarter people than me; but rather about everything interacting with the code itself. Some of this article is related to the programming languages I use most often at the moment, which are PHP and JavaScript/TypeScript, but I try to keep it as general as possible.",[23,31,33],{"id":32},"conventional-commits","Conventional Commits",[16,35,36,42,43,47,48,51,52,55],{},[37,38,33],"a",{"href":39,"rel":40},"https://www.conventionalcommits.org/en/v1.0.0/",[41],"nofollow"," have fortunately become the standard for many open-source projects, and I fully embrace it.\nThey suggest a clear, short commit message that indicates the scope of the change (",[44,45,46],"code",{},"fix:",", ",[44,49,50],{},"feat:"," ",[44,53,54],{},"chore:",", etc.), which can be useful for a number of reasons:",[57,58,59,63,66],"ol",{},[60,61,62],"li",{},"Reviewers see immediately what changes they should look out for when reading the diff just by looking at the commit message.",[60,64,65],{},"It encourages smaller commits: different concerns should be split into multiple commits in order to follow Conventional Commits. This also improves readability for code review.",[60,67,68,69,74],{},"Changelogs: Tools like ",[37,70,73],{"href":71,"rel":72},"https://github.com/unjs/changelogen",[41],"changelogen"," can use the commit message structure provided by Conventional Commits to automatically generate a Changelog.",[23,76,78],{"id":77},"signed-commits","Signed Commits",[80,81,82],"blockquote",{},[16,83,84],{},"While this might not be entirely matching the theme of this article, I want to mention it anyway when writing on the topic of commits, because I think it's important.",[16,86,87],{},"I always wanted to do signed commits, and it took me some time to initially set up on my Mac and have it synced with Keychain, but I think it's totally worth the effort.",[16,89,90,91,94],{},"When I see the green ",[44,92,93],{},"verified"," badge attached to someone's commit on GitHub, my mind immediately interprets this as a sign of quality.",[16,96,97,98,102],{},"But just like with SSL and every other cryptographic certificate, this only ensures ",[99,100,101],"strong",{},"authenticity"," of the source, and not more. Of course everyone, even malicious actors, can verify their commits. So this doesn't replace a required level of trust in the source itself.",[23,104,106],{"id":105},"comments","Comments",[16,108,109],{},"When it comes to code comments, I mostly try to keep it concise. If something needs a lengthy explanation, the implementation isn't that good to begin with.",[16,111,112,113,117,118,121,122,124,125,127],{},"Comments should always serve a purpose. They should explain the ",[114,115,116],"em",{},"why"," and not the ",[114,119,120],{},"what",". If you structure your code well, the ",[114,123,120],{}," should be clear from the code itself.\nBut that only applies to self-contained code and not the whole project. User-facing code from e.g. a library or framework should explicitly document the ",[114,126,120],{},".",[16,129,130,131,133,134,137],{},"For that use case, doc blocks are a great way to document the ",[114,132,120],{}," and ",[114,135,136],{},"how"," of a function or class. I try to keep them concise, but not missing any important information.",[139,140,145],"pre",{"className":141,"code":142,"language":143,"meta":144,"style":144},"language-php shiki shiki-themes gruvbox-light-hard","/**\n* Parse, process and save the file.\n*\n* @param string $path The absolute path to the file.\n*/\npublic function processFile(string $path): void\n{\n  // Implementation\n}\n","php","",[44,146,147,156,162,168,184,190,229,235,241],{"__ignoreMap":144},[148,149,152],"span",{"class":150,"line":151},"line",1,[148,153,155],{"class":154},"s-UKz","/**\n",[148,157,159],{"class":150,"line":158},2,[148,160,161],{"class":154},"* Parse, process and save the file.\n",[148,163,165],{"class":150,"line":164},3,[148,166,167],{"class":154},"*\n",[148,169,171,174,178,181],{"class":150,"line":170},4,[148,172,173],{"class":154},"* ",[148,175,177],{"class":176},"sXoUb","@param",[148,179,180],{"class":176}," string",[148,182,183],{"class":154}," $path The absolute path to the file.\n",[148,185,187],{"class":150,"line":186},5,[148,188,189],{"class":154},"*/\n",[148,191,193,197,200,204,208,212,215,219,222,226],{"class":150,"line":192},6,[148,194,196],{"class":195},"sQWTk","public",[148,198,199],{"class":195}," function",[148,201,203],{"class":202},"sMFC1"," processFile",[148,205,207],{"class":206},"sYPru","(",[148,209,211],{"class":210},"snpkh","string",[148,213,214],{"class":206}," $",[148,216,218],{"class":217},"suDhl","path",[148,220,221],{"class":206},")",[148,223,225],{"class":224},"s0r2k",":",[148,227,228],{"class":210}," void\n",[148,230,232],{"class":150,"line":231},7,[148,233,234],{"class":206},"{\n",[148,236,238],{"class":150,"line":237},8,[148,239,240],{"class":154},"  // Implementation\n",[148,242,244],{"class":150,"line":243},9,[148,245,246],{"class":206},"}\n",[16,248,249,250,255],{},"Another exception to that rule is when a comment's purpose is to be documentation, like a Laravel configuration file. While I don't quite craft my comments into such an explicit form as ",[37,251,254],{"href":252,"rel":253},"https://x.com/calebporzio/status/1499390772080037894",[41],"Taylor Otwell does",", I like to approximate his style.",[16,257,258,259,262],{},"Here's an example of his out of Laravel's default ",[44,260,261],{},"app"," configuration file:",[139,264,266],{"className":141,"code":265,"language":143,"meta":144,"style":144},"/*\n|--------------------------------------------------------------------------\n| Application Name\n|--------------------------------------------------------------------------\n|\n| This value is the name of your application, which will be used when the\n| framework needs to place the application's name in a notification or\n| other UI elements where an application name needs to be displayed.\n|\n*/\n",[44,267,268,273,278,283,287,292,297,302,307,311],{"__ignoreMap":144},[148,269,270],{"class":150,"line":151},[148,271,272],{"class":154},"/*\n",[148,274,275],{"class":150,"line":158},[148,276,277],{"class":154},"|--------------------------------------------------------------------------\n",[148,279,280],{"class":150,"line":164},[148,281,282],{"class":154},"| Application Name\n",[148,284,285],{"class":150,"line":170},[148,286,277],{"class":154},[148,288,289],{"class":150,"line":186},[148,290,291],{"class":154},"|\n",[148,293,294],{"class":150,"line":192},[148,295,296],{"class":154},"| This value is the name of your application, which will be used when the\n",[148,298,299],{"class":150,"line":231},[148,300,301],{"class":154},"| framework needs to place the application's name in a notification or\n",[148,303,304],{"class":150,"line":237},[148,305,306],{"class":154},"| other UI elements where an application name needs to be displayed.\n",[148,308,309],{"class":150,"line":243},[148,310,291],{"class":154},[148,312,314],{"class":150,"line":313},10,[148,315,189],{"class":154},[16,317,318],{},"I find this to be a pure joy to read, but only applicable in the right context.",[23,320,322],{"id":321},"dead-code","Dead Code",[16,324,325,326],{},"I guess this should be common practice by now, but I've been guilty myself in the past and still see it way too often: ",[99,327,328],{},"Don't comment out code. Just delete it.",[16,330,331],{},"Commented out code is a sign of laziness and lack of confidence in your own decisions. It shows that you don't trust your own judgement and are afraid to make mistakes.\nDead code just makes things unreadable, and add unnecessary noise to the codebase.",[16,333,334],{},"Some common arguments I hear against this strict approach:",[80,336,337],{},[16,338,339],{},"\"But I wanna know what was there before\"",[16,341,342],{},"Use the Git history.",[80,344,345],{},[16,346,347],{},"\"But I wanna know who changed it\"",[16,349,350,351,127],{},"Use ",[37,352,355],{"href":353,"rel":354},"https://git-scm.com/docs/git-blame",[41],"Git blame",[80,357,358],{},[16,359,360],{},"\"But I want to know why it was deleted\"",[16,362,350,363,367],{},[37,364,366],{"href":365},"#conventional-commits","conventional commits"," and look at the commit message.",[80,369,370],{},[16,371,372],{},"\"But I want to test things out and maybe revert it\"",[16,374,375],{},"Use a different branch for that.",[16,377,378],{},"In short, if you need to comment out code, you're using Git wrong.",[380,381,382],"style",{},"html pre.shiki code .s-UKz, html code.shiki .s-UKz{--shiki-default:#928374;--shiki-default-font-style:italic}html pre.shiki code .sXoUb, html code.shiki .sXoUb{--shiki-default:#9D0006;--shiki-default-font-style:italic}html pre.shiki code .sQWTk, html code.shiki .sQWTk{--shiki-default:#AF3A03}html pre.shiki code .sMFC1, html code.shiki .sMFC1{--shiki-default:#B57614}html pre.shiki code .sYPru, html code.shiki .sYPru{--shiki-default:#7C6F64}html pre.shiki code .snpkh, html code.shiki .snpkh{--shiki-default:#9D0006}html pre.shiki code .suDhl, html code.shiki .suDhl{--shiki-default:#076678}html pre.shiki code .s0r2k, html code.shiki .s0r2k{--shiki-default:#427B58}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":144,"searchDepth":158,"depth":158,"links":384},[385,386,387,388,389],{"id":25,"depth":158,"text":26},{"id":32,"depth":158,"text":33},{"id":77,"depth":158,"text":78},{"id":105,"depth":158,"text":106},{"id":321,"depth":158,"text":322},"md",true,{},null,"/blog/code-clarity","---\narticle_published_time: 2025-04-20T10:41:34+0200\narticle_last_modified_time: 2025-04-23T21:21:14+0200\nis_published: true\n---\n\n# Code Clarity\n\nHow good practices around your code can improve your workflow.\n\nI want to share some of the conventions I try to follow in my projects, and why I use them in this way.\n\n## Introduction\n\nThese are some practices that improve oversight and collaboration in projects for me. This is not about code style itself: there are a lot of books out there about that, written by way smarter people than me; but rather about everything interacting with the code itself. Some of this article is related to the programming languages I use most often at the moment, which are PHP and JavaScript/TypeScript, but I try to keep it as general as possible.\n\n## Conventional Commits\n\n[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) have fortunately become the standard for many open-source projects, and I fully embrace it.\nThey suggest a clear, short commit message that indicates the scope of the change (`fix:`, `feat:` `chore:`, etc.), which can be useful for a number of reasons:\n\n1. Reviewers see immediately what changes they should look out for when reading the diff just by looking at the commit message.\n2. It encourages smaller commits: different concerns should be split into multiple commits in order to follow Conventional Commits. This also improves readability for code review.\n3. Changelogs: Tools like [changelogen](https://github.com/unjs/changelogen) can use the commit message structure provided by Conventional Commits to automatically generate a Changelog.\n\n## Signed Commits\n\n> While this might not be entirely matching the theme of this article, I want to mention it anyway when writing on the topic of commits, because I think it's important.\n\nI always wanted to do signed commits, and it took me some time to initially set up on my Mac and have it synced with Keychain, but I think it's totally worth the effort.\n\nWhen I see the green `verified` badge attached to someone's commit on GitHub, my mind immediately interprets this as a sign of quality.\n\nBut just like with SSL and every other cryptographic certificate, this only ensures **authenticity** of the source, and not more. Of course everyone, even malicious actors, can verify their commits. So this doesn't replace a required level of trust in the source itself.\n\n## Comments\n\nWhen it comes to code comments, I mostly try to keep it concise. If something needs a lengthy explanation, the implementation isn't that good to begin with.\n\nComments should always serve a purpose. They should explain the _why_ and not the _what_. If you structure your code well, the _what_ should be clear from the code itself.\nBut that only applies to self-contained code and not the whole project. User-facing code from e.g. a library or framework should explicitly document the _what_.\n\nFor that use case, doc blocks are a great way to document the _what_ and _how_ of a function or class. I try to keep them concise, but not missing any important information.\n\n```php\n/**\n* Parse, process and save the file.\n*\n* @param string $path The absolute path to the file.\n*/\npublic function processFile(string $path): void\n{\n  // Implementation\n}\n```\n\nAnother exception to that rule is when a comment's purpose is to be documentation, like a Laravel configuration file. While I don't quite craft my comments into such an explicit form as [Taylor Otwell does](https://x.com/calebporzio/status/1499390772080037894), I like to approximate his style.\n\nHere's an example of his out of Laravel's default `app` configuration file:\n\n```php\n/*\n|--------------------------------------------------------------------------\n| Application Name\n|--------------------------------------------------------------------------\n|\n| This value is the name of your application, which will be used when the\n| framework needs to place the application's name in a notification or\n| other UI elements where an application name needs to be displayed.\n|\n*/\n```\n\nI find this to be a pure joy to read, but only applicable in the right context.\n\n## Dead Code\n\nI guess this should be common practice by now, but I've been guilty myself in the past and still see it way too often: **Don't comment out code. Just delete it.**\n\nCommented out code is a sign of laziness and lack of confidence in your own decisions. It shows that you don't trust your own judgement and are afraid to make mistakes.\nDead code just makes things unreadable, and add unnecessary noise to the codebase.\n\nSome common arguments I hear against this strict approach:\n\n> \"But I wanna know what was there before\"\n\nUse the Git history.\n\n> \"But I wanna know who changed it\"\n\nUse [Git blame](https://git-scm.com/docs/git-blame).\n\n> \"But I want to know why it was deleted\"\n\nUse [conventional commits](#conventional-commits) and look at the commit message.\n\n> \"But I want to test things out and maybe revert it\"\n\nUse a different branch for that.\n\nIn short, if you need to comment out code, you're using Git wrong.\n",{"title":5,"description":18},"blog/code-clarity","FQ07q1bpDcEmNqbDRiRCa-EbhbxxzySXOW9ithlCZ4E",1774690999804]