کامنت گذاری در CleanCode (قسمت آخر)

خودداری از نشانگرهای موقعیتی-Avoid positional markersکامنت ها را در خارج از کد اصلی قرار ندهید-Don't leave commented out code in your codebaseکامنت ژورنالی نداشته باشید-Don't have journal commentsفقط چیزهایی را کامنت کنید که پیچیدگی منطق تجاری دارند-Only comment things that have business logic complexityخودداری از نشانگرهای موقعیتی Avoid positional markersآنها معمولاً فقط سر و صدا می کنند.بگذارید توابع و نام های متغیر به همراه تورفتگی و قالب بندی مناسب ، ساختار بصری را به کد شما بدهند.Bad://////////////////////////////////////////////////////////////////////////////// // Scope Model Instantiation //////////////////////////////////////////////////////////////////////////////// var model = new[] { menu: 'foo', nav: 'bar' }; //////////////////////////////////////////////////////////////////////////////// // Action setup //////////////////////////////////////////////////////////////////////////////// void Actions() { // ... };Bad:#region Scope Model Instantiation var model = { menu: 'foo', nav: 'bar' }; #endregion #region Action setup void Actions() { // ... }; #endregionGood:var model = new[] { menu: 'foo', nav: 'bar' }; void Actions() { // ... };کامنت ها را در خارج از کد اصلی قرار ندهید Don't leave commented out code in your codebaseکنترل نسخه(Version control) به یک دلیل وجود دارد.کد قدیمی را در history بگذارید.Bad:doStuff(); // doOtherStuff(); // doSomeMoreStuff(); // doSoMuchStuff();Good:doStuff();کامنت ژورنالی نداشته باشید Don't have journal commentsبه یاد داشته باشید ، از کنترل نسخه استفاده کنید! دیگر نیازی به کدهای مرده ، کد comment شده و به خصوص comment های ژورنالی نیست.برای دریافت تاریخچه از log git استفاده کنید!Bad:/** * 2018-12-20: Removed monads, didn't understand them (RM) * 2017-10-01: Improved using special monads (JP) * 2016-02-03: Removed type-checking (LI) * 2015-03-14: Added combine with type-checking (JR) */ public int Combine(int a,int b) { return a + b; }Good:public int Combine(int a,int b) { return a + b; }فقط چیزهایی را کامنت کنید که پیچیدگی منطق تجاری دارند Only comment things that have business logic complexityنظرات عذرخواهی است ، نه یک الزام.کد خوب اغلب خود را مستند می کند.Bad:public int HashIt(string data) { // The hash var hash = 0; // Length of string var length = data.length; // Loop through every character in data for (var i = 0; i < length; i++) { // Get character code. const char = data.charCodeAt(i); // Make the hash hash = ((hash << 5) - hash) + char; // Convert to 32-bit integer hash &= hash; } }Better but still Bad:public int HashIt(string data) { var hash = 0; var length = data.length; for (var i = 0; i < length; i++) { const char = data.charCodeAt(i); hash = ((hash << 5) - hash) + char; // Convert to 32-bit integer hash &= hash; } }اگر یک comment توضیح داد که کد درحال انجام چیست ،احتمالاً این یک comment بی فایده است و می تواند با یک نام متغیر یا تابعی که به خوبی شناخته شده باشد ، پیاده سازی شود.comment در کد قبلی می تواند با تابعی به نام ConvertTo32bitInt جایگزین شود ، بنابراین این comment هنوز بی فایده است.با این وجود دشوار است که با کدی بیان کنید چرا توسعه دهنده الگوریتم هش djb2 را به جای sha-1 یا یک تابع هش دیگر انتخاب می کند.در این صورت یک comment قابل قبول است.Good:public int Hash(string data) { var hash = 0; var length = data.length; for (var i = 0; i < length; i++) { var character = data[i]; // use of djb2 hash algorithm as it has a good compromise // between speed and low collision with a very simple implementation hash = ((hash << 5) - hash) + character; hash = ConvertTo32BitInt(hash); } return hash; } private int ConvertTo32BitInt(int value) { return value & value; }برای مشاهده ابزار های visual studio برای نوشتن کد تمیز و همچنین خواند همین مطالب برای زبان های دیگر به منبع این بخش مراجعه کنید.