保持维护良好且易于理解的编码部分的技术？ [英] techniques to keep well maintained and understandable coding parts?

问题描述

'



技术可以保持良好的维护和可理解的编码部分？



我是想知道装饰的不同之处是什么，让代码对未来的开发人员来说更具可读性。'''





目前我知道follwinf技术



评论该部分并写下关于代码范围的描述..



//这是为仅限Mastwer登录使用



使用关键字#region #end region将代码分成几个部分



＃地区公司详情



编码部分



#end region



＃region目标详情



编码部分



#end region



什么是其他技术

解决方案

评论和地区可能会有所帮助，但它们必须相关：A评论必须添加到t他编写代码，不重复它或描述编译器将导致它做什么。自记录代码（通过良好的模块化和变量名称选择）通常更有用，因为它对于当前代码往往是准确的，一旦修改开始，这可能是注释的问题。更糟糕的是一个错误的评论！



一般来说，我评论方法而不是方法 - 如果它需要另一个评论那么有一个很好的论据，它应该无论如何都要成为它自己的方法。



MXL注释是必须的：它们意味着Intellisense选择了方法描述，这使得遵循该方法变得更加容易参数如此。我的默认项目模板将其打开以确保它们已生成（它会为没有XML注释的公共方法生成编译器警告）。



区域很好 - 但仅限如果使用得当：我使用它们来标记我的代码中的部分：一个区域中的字段，另一个区域中的属性，构造函数等等。这里的例子是标准的空白类模板VS现在给我：

 使用系统; 
 使用 System.Collections.Generic; 
 使用 System.Linq; 
 使用 System.Text; 
 
 命名空间 MyWallet 
 {
  ///   <  摘要 >  
   ///   TODO：班级说明
   ///   <   / summary  >  
   public   class  MyNewClass 
 {
   #region constants 
    #endregion 
  
   #region字段
    #region内部
    #endregion 
  
   #region属性基础
    #endregion 
    #endregion 
  
   #region属性
    #endregion 
  
   #region正则表达式
    #endregion 
  
   #region Enums 
    #endregion 
  
   #region Constructors 
   ///   <  摘要 < span class =code-summarycomment>>  
   ///  默认构造函数
   ///   <   / summary  >  
   public  MyNewClass（）
 {
  //   TODO：默认构造函数 
} 
   #endregion 
  
   #region事件
    #region事件构造函数
    #endregion 
  
   #region事件处理程序
   < span class =code-region> #endregion 
    #endregion 
  
   #region公共方法
    #endregion 
  
   #region覆盖
    #endregion 
  
   #region私有方法
    #endregion 
 } 
} 

我讨厌当人们试图在一个方法中使用一个区域来将流分解成各个部分时 - 通常，最好用不同的方法来完成。



将警告视为错误：同样，我在默认项目中设置了此选项。现代编译器并不愚蠢：一般来说，如果它抱怨什么，那么你做了一些愚蠢的事情并没有实现它。在编译时捕获这些比在运行时出现奇怪问题容易得多！



最重要的是：做正确的事情（不要采取快捷方式 - 他们会在以后咬你），除非有充分的理由，否则不要使用聪明的代码 - 然后用它解释为什么需要它以及它是如何工作的呢？遵循OOP的良好做法;尽可能重复使用工作代码。



并记住：规范将会改变。因此，设计您的代码以便可以更改。

我觉得您开始考虑错误结束的问题，缺少最高优先级的考虑因素并跳转到最不优先的项目。对我来说，实现良好可维护代码的考虑应该以某种方式优先考虑：

1. 适合每个项目的声音架构和设计。一些重要的项目将遵循以下原则：
   
   单一真相来源： http：//en.wikipedia .org / wiki / Single_Point_of_Truth [ ^ ]，
   
   不要重复自己： http://en.wikipedia.org/wiki/Don%27t_repeat_yourself [ ^ ]，
   
   关注点分离 http://en.wikipedia.org/wiki/Separation_of_concerns [ ^ ]，
   
   .....等等......
   
   
   
   了解相关的架构模式和设计模式非常重要，但是它们是sh只能通过批判性思考和分析项目目标，团队成员的背景，甚至团队成员的个人品味以及其他特殊因素来使用：
   
   http://en.wikipedia.org/wiki/Architectural_pattern [ ^ ]，
   
   http：// en.wikipedia.org/wiki/Design_pattern [ ^ ]。
   
   
   
   但我认为知道反模式更为重要： http://en.wikipedia.org/wiki/Anti-pattern [ ^ ]。
   
   
   
   你需要知道众所周知的和你自己的反模式好吧，好吧
3. 除了以上各项之外，您还需要根据分解到编程单元（如类）来设计代码。您可以考虑使用嵌套类和其他类型或单独的类型，部分类声明和其他变体。您需要分解代码的各个部分，同时牢记修改代码的过程。例如，如果使用分部类声明，则可以将某个方面放在单独的部分中，这样可以更容易地找到相关代码，了解它所负责的方面。同时，当你想要去宣言时会花费更多的时间：IDE会向你显示多个部分供你选择。
   
   
   
   类似的考虑将适用于此级别的其他决策。
4. 上一项中描述的级别的考虑因素将决定下一级决策：如何在文件之间分配代码，如何文件应按目录命名和分发。例如，如果您具有可以称为MyUI.Setup，MyUI.Events，MyUI.Storage的部分功能，或者可以通过应用程序的某些语义方面以相同的方式调用它们：MyUI。 InstrumentatonSetting，MyUI.DataManagement或类似的东西，这些复合名称可以成为文件的名称。但是，如果要将不同的方面放在不同的子目录中，则可能具有相同文件的相同文件名，可以通过目录名来区分它们。
   
   
   
   这个与您可以考虑在命名空间中命名的级别相同。重要的是要理解命名空间不会以任何方式影响功能，但它们可以使代码或多或少地易于理解。许多人遵循默认的Visual Studio规则：在每个子目录的每个命名空间名称的末尾添加单独的命名空间后缀，但没有任何东西强迫您这样做。您可以发明任何命名策略（如果有的话），任何适合您的命名策略。重要的是你要考虑项目维护和事情。
5. 你需要考虑你的命名风格。但是，您需要从一开始就开始考虑它。对于项目维护，这非常关键。作为起点，我总是推荐.NET的当前Microsoft命名约定。然而，良好的命名是整个艺术。如何使名称不太长，但又非常可读并反映出目的？它需要一些相当丰富的经验。
   
   
   
   一个非常基本的建议：永远不要违反正确的英文拼写，不要缩写。考虑您忘记了名称，但希望按符号查找定义。你只知道这个想法。使用正确的字典拼写将大大减少搜索选项的数量。
6. 只有在最后一级，您需要考虑代码的格式和排列：格式，空行，注释和#region。
   
   
   
   顺便说一句，最低优先级并不意味着不那么重要。一点也不。我的优先列表是按照思维顺序建立的，及时：你应该先考虑什么，接下来要考虑什么。所有项目都非常重要。

这只是我的一个想法：我想，如果你觉得很多需要很多C＃ #region标记或方式更详细的注释，这意味着您已经无法正确构建代码。回到我列表中的优先级较高的项目，找出你做得不好的地方。







据我所知，你问过这种技术如部分声明。



但这个话题非常非常简单，并且完全由微软文档描述：

http://msdn.microsoft.com/ en-us / library / wa80x488％28v = vs.110％29.aspx [ ^ ]。



但是，将其用于维护良好的代码结构是不那么琐碎。我想提请你注意一个重要的可能性：如何在同一个班级中分离不同的方面。首先，请注意您不必在所有部分重复所有继承列表。你不应该。您应该仅提及单独方面所需的内容。假设您要执行一些设置工作并在一个部分中声明所有基本成员，并在另一个部分中实现某个接口。让我们看看它看起来多么简洁：

 使用 ThisNamespace; 
 使用 AnotherNamespace; 
 使用 MyBaseClass = SomeDifferentNamespce.MyBaseClass; 
 
 内部 部分  class  MyClass：MyBaseClass {
 
  //   ...  
 
  void 设置（）{
 SetupThisAspect（）;  //  通常可以定义被调用的方法 
 SetupAnotherAspect（）;  //  在其他课程部分 
  //   ...  
}  //  设置 
 
  //   ...  
 
}  //   class MyClass  

然后，在同一个班级的一个单独部分中，需要再次提及上述内容，或者根本没有内容：

< pre lang =c＃> 使用 SomeVeryDifferent.Namespace;
使用 AnotherDifferent.Namespace;

内部 public interface IMyInterface {
void MyMethod;
// ...
} // interface IMyInterface

internal partial class MyClass：IMyInterface { // 无需提及：MyBaseClass

void IMyInterface.MyMethod（）{ / * ... * / }
// ... ine IMyInterface.SomethingElse ...
// ...

// local成员只帮助实现IMyInterface ...
// ...

} // 类MyClass

你得到的照片吗？

-SA

对我来说，创建可理解/可维护代码的最大好处是开发或采用标准。以下是我的标准要点：



- 所有类别（除了小的类别）都组织成以下区域：字段，属性，事件，构造/解构，公共方法和私人方法。可以根据内部方法或受保护方法等内容添加其他区域。任何区域都不应为空（如果是，请将其删除）。



- 公共/受保护的界面始终记录在/// xml doc标签中，不公开/ protected方法应该没有记录。私人方法也应记录在案。



- 所有方法，属性，类名和事件都是PascalCased（也称为CamelCasing）。



- 所有私有字段前面都有下划线（_）。



- 所有局部变量和方法参数都是lowerCamelCase。 />


- 所有变量都应该是可以理解的，唯一允许的单个字母变量是指标，i表示索引，x表示水平方向，y表示垂直方向等。



- 如果某个方法需要注释来了解正在发生的事情，那么它应该被重构。



等...我的个人规则手册还有更多内容，其中大部分内容都来自 Microsoft编码标准 [ ^ ]。



重要的是一致性，如果你能创造一致的风格，那么那些人阅读你的代码可能需要一点点来理解你的风格，但从长远来看会使阅读变得更容易。

Hi,'

techniques to keep well maintained and understandable coding parts?

I was wondering what are the different things to decorate and make the code much readable for future developer.'''


Currently i know follwinf techniques

comment the part and write description regarding scope of the code..

// This is for Mastwer login use only

Dividing the code into sections using the keyword #region #end region

# region Company Details

coding parts

# end region

# region Objectives details

coding part

# end region

what are the other techniques

解决方案

Comments and regions can be helpful, but they have to be relevant: A comment must add to the code, not repeat it or describe what the compiler will cause it to do. Self documenting code (by means of good modularisation and variable name selection) is generally more use as it tends to be accurate for the current code, which can be a problem with comments once modifications start. There is little more annoying that a wrong comment!

Generally, I comment methods rather than within methods - if it needs another comment then there is a good argument that it should be a method of it's own anyway.

MXL comments are a must: they mean that Intellisense picks up the method description and that makes it a lot easier to follow the method parameters as so forth. My default project template turns that on to make sure they are generated (it generates a compiler warning for public methods without XML comments then).

Regions are good - but only if used properly: I use them to mark out the sections in my code: fields in one region, properties in another, constructors and so forth. Here for example is the standard blank class template VS now gives me:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace MyWallet
    {
    /// <summary>
    /// TODO: Class description
    /// </summary>
    public class MyNewClass
        {
        #region Constants
        #endregion

        #region Fields
        #region Internal
        #endregion

        #region Property bases
        #endregion
        #endregion

        #region Properties
        #endregion

        #region Regular Expressions
        #endregion

        #region Enums
        #endregion

        #region Constructors
        /// <summary>
        /// Default constructor
        /// </summary>
        public MyNewClass()
            {
            // TODO: Default constructor
            }
        #endregion

        #region Events
        #region Event Constructors
        #endregion

        #region Event Handlers
        #endregion
        #endregion

        #region Public Methods
        #endregion

        #region Overrides
        #endregion

        #region Private Methods
        #endregion
        }
    }

I hate it when people try to use a region within a method to break up the flow into sections - generally, that is better done with separate methods instead.

Treat warnings as errors: Again, I have this option set in my default project. Modern compilers aren't stupid: generally if it is complaining about something then you have done something stupid and haven't realised it. It's a lot easier to catch these at compile time than as a "odd-case" problem at run time!

Above all: Do things properly (don't take shortcuts - they will bite you later), don;t use "clever code" unless there is a good reason for it - and then comment it very well indeed with an explanation of why it's needed as well as how it works; follow OOPs good practices; reuse working code when possible.

And remember: the specification will change. So design your code so that it can be changed.

I feel that you start considering the problem with wrong end, missing highest priority considerations and jumping to least priority items. To me, the considerations for achieving well maintainable code should be prioritized in some way like:

1. Sound architecture and design adequate and customized to each project. Some important items would be following the principles like:
   Single Source of Truth: http://en.wikipedia.org/wiki/Single_Point_of_Truth[^],
   Don't repeat yourself: http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[^],
   Separation of Concerns http://en.wikipedia.org/wiki/Separation_of_concerns[^],
   .....and more…
   
   It would be very important to know relevant architectural patterns and design patterns, but they should be used only as a result of critical thinking and analysis the project goals, background of team members, even personal taste of the team members, and other particular factors:
   http://en.wikipedia.org/wiki/Architectural_pattern[^],
   http://en.wikipedia.org/wiki/Design_pattern[^].
   
   But I think it's even more important to know anti-patterns: http://en.wikipedia.org/wiki/Anti-pattern[^].
   
   You need to know well-known and your own anti-patterns very well, be able to identify them and avoid by all means.
2. On top of above items, you need to design your code in terms of decomposition into programming units, such as classes. You can consider using nested classes and other types or separate types, partial class declarations, and other variants. You need to decompose the parts of the code keeping in mind the process of modification of the code. For example, if you use partial class declaration, you can put some aspect in a separate part, that will make it easier to find relevant code knowing the aspect it is responsible for. At the same time, it would take up a little more time when you want to "go to the declaration": the IDE will show you more than one part to choose from.
   
   The similar considerations will be applied to other decisions of this level.
3. The considerations at the level described in a previous item will dictate the next level of decisions: how to distribute code between files, how the files should be named and distributed by directories. For example, if you have parts of functionality which can be called "MyUI.Setup", "MyUI.Events", "MyUI.Storage", or they can be called the same way by some semantic aspects of the application: "MyUI.InstrumentatonSetting", "MyUI.DataManagement" or something like that, these compound names can become the names of the files. However, if you want to put different aspects in different sub-directories, you may have identical file names of same file, they can be distinguished by directory names.
   
   This is the same level where you can think about naming in your namespaces. It's important to understand that namespaces don't affect functionality in any way, but they can make code more or less comprehensible. Many follow the default Visual Studio rule: adding separate namespace suffix at the end of each namespace name per sub-directory, but nothing forces you to do so. You can invent any naming policy (if any at all), anything which suites you. It is only important that you take project maintenance into account and thing about it.
4. You need to think through your naming styles. However, you need to start thinking of it just a bit from the very beginning. For project maintenance, it is really critical. As as starting point, I always recommend current Microsoft naming conventions for .NET. However, good naming is the whole art. How to make names not too long and yet very readable and reflecting the purpose? It needs some considerable experience.
   
   One very basic advice: never ever violate correct English spelling, don't abbreviate. Consider you forget the name but want to find the definition by symbol. You know only the idea. Using correct dictionary spelling will highly reduce the number of search options.
5. And only on the last level you need to think about formatting and arrangement of your code: format, empty lines, comments and "#region".
   
   By the way, lowest priority does not mean less important. Not at all. My prioritized list is rather build by the order of thinking, in time: what should you consider first and what next. All items are very important.

Here is just one my idea: I think, if you feel a really strong need for many C# "#region" markup or way more detailed comments, it means that you already failed to properly structure your code. Get back to the higher priority items in my list and identify where you did it poorly.

[EDIT]

As I understand, you asked about such technique as partial declarations.

But this topic is really, really simple and is fully described by Microsoft documentations:
http://msdn.microsoft.com/en-us/library/wa80x488%28v=vs.110%29.aspx[^].

However, applying it for well maintainable code structure is less trivial. I want to bring to your attention one important possibility: how to separate different aspects in the same class. First of all, pay attention that you don't have to repeat all the inheritance list in all part. And you should not. You should mention only what you need for a separate aspect. Suppose you want to perform some setup work and declare all basic members in one part, and implement some interface in another. Let's see how neat it might look:

using ThisNamespace;
using AnotherNamespace;
using MyBaseClass = SomeDifferentNamespce.MyBaseClass;

internal partial class MyClass : MyBaseClass {

   //...

   void Setup() {
        SetupThisAspect();     // the called methods can typically be defined
        SetupAnotherAspect();  // in other class parts
        //...
   } //Setup

   //...

} //class MyClass

And then, in a separate part of the same class, very little of the above, or nothing at all, need to be mentioned again:

using SomeVeryDifferent.Namespace;
using AnotherDifferent.Namespace;

internal public interface IMyInterface {
    void MyMethod;
    //...
} //interface IMyInterface

internal partial class MyClass : IMyInterface { // no need to mention ": MyBaseClass"

    void IMyInterface.MyMethod() { /* ... */ }
    //... ine IMyInterface.SomethingElse...
    //...

    // local members only helping to implement IMyInterface...
    //...

} //class MyClass

Are you getting the picture?

—SA

For me, the biggest thing to creating understandable/maintainable code is to either develop or adopt a standard. Here are the major points of my standard:

- All classes (except trivially small ones) are organized into the following regions: Fields, Properties, Events, Construction/Deconstruction, Public Methods, and Private Methods. Other regions can be added as necessary for things like Internal Methods or Protected Methods. No region should be blank (if it is, delete it).

- The public/protected interface is always documented with the /// xml doc tags, no public/protected method should be left undocumented. Private methods should be documented as well.

- All methods, properties, class names, and events are PascalCased (also called CamelCasing).

- All private fields are preceded by an underscore (_).

- All local variables and method parameters are lowerCamelCase.

- All variables should be understandable, the only single letter variables allowed are indicies, i for index, x for horizontal direction, y for vertical direction, etc.

- If a method requires comments to understand what is going on, it should be refactored.

Etc... There are more to my "personal rule book", most of which follow Microsoft Coding Standards[^].

The big thing is consistency, if you can create a consistent style, then people who read your code may take a little bit to understand your style, but will make reading it much easier in the long run.

这篇关于保持维护良好且易于理解的编码部分的技术？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！