Is there a comment style for starting a section in the code?-CodePudding

I'm referring to cases where I have different functionality in the class that it wouldn't make sense to break down to smaller classes.

For example, in Python, I personally like to use

class DataStream:

  ################################
  # Read stream functionality
  ################################

  def read():
    pass

  def decode():
    pass

  ################################
  # Parse stream functionality
  ################################

  def exract_data():
    pass

  def map_data_types():
    pass

  ################################
  # Analyze functionality
  ################################

  def aggregated_data():
    pass

  def deduce_insights():
    pass

AFAIK, there is no convention for such comments.

Is there a convention for this in Java? Or any format that Intellij can make something useful out of it? For example, it would be great if Intellij would be able to collapse these sections.

CodePudding user response：

Instead of relying on grouping related functional methods in close proximity in the source code and indicating the relationship with code comments, you should design and implement your code in way that takes advantage of features of the language and makes the purpose explicit.

For example, instead of grouping cooking methods and baking methods in the same class, you could implement this using different classes:

public class BakingOven{

    public Result bakeBread(){
    }

    public Result bakeCake(){
    }
}


public class FryingPan{

    public Result fryChicken(){
    }
    
    public Result frySteak(){
    }
}

This could be taken further by passing what it is to be baked or fried as a parameter, or you could indentify commmon interfaces like Fry, or Bake and have the classes implement those interfaces.

This is more of a design and how to structure your code more clearly type of problem than thinking about it as a documentation type problem.

CodePudding user response：

You have some fundamental problems in your example.

class Kitchen:

  ################################
  # Getters/Setters
  ################################

  def get_groceries():
    pass

  ################################
  # Cooking Methods
  ################################

  def cook_chicken():
    pass

  def cook_pasta():
    pass

  ################################
  # Baking Methods
  ################################

  def bake_bread():
    pass

  def bake_cake():
    pass

First Kitchens don't get groceries. Which means your Kitchen is more of a data structure in some aspects than an Object; because, you are exposing groceries to something else, which the kitchen is probably supposed to do.

Second, you are creating compound methods, such that every new item you need to cook or bake will require a new method. This is bad naming practice because it means the Kitchen is not extendable without recompiling the code.

    def cook( recipe ):

would be a much better design, as it could then take any recipe and cook it.

Finally, baking and cooking are the same kind of transformation, they both convert ingredients into finished edible foods. As a result of history and techniques, these tend to have different names; but, cooking a loaf of bread is a perfectly valid way of expressing baking a loaf of bread at a high level (just like transporting yourself to the store is a perfectly valid way of saying walking to the store).

So your overall class design probably should be:

class Kitchen:

    def add( grocery )

    def use( grocery )

    def cook( recipe )

And now the class is both smaller and better designed, extensible and easier to debug, to complete the picture, let's implement recipes for chicken, pasta, bread, and cake:

interface Recipe:

   abstract def cook():

class ChickenRecipe implements Recipe:

   def cook(Kitchen kitchen):
       kitchen.use("chicken breast")
       kitchen.use("oil")
       kitchen.use("salt")
       kitchen.use("pepper")
       return "cooked chicken"

class PastaRecipe implements Recipe:

   def cook(Kitchen kitchen):
       kitchen.use("pasta")
       kitchen.use("water")
       kitchen.use("salt")
       kitchen.use("oil")
       return"cooked pasta"

class BreadRecipe implements Recipe:
    
   def cook(Kitchen kitchen):
       kitchen.use("flour")
       kitchen.use("water")
       kitchen.use("salt")
       kitchen.use("yeast")
       return "bread"

class CakeRecipe implments Recipe:

   def cook(Kitchen kitchen):
       kitchen.use("flour")
       kitchen.use("water")
       kitchen.use("salt")
       kitchen.use("sugar")
       kitchen.use("butter")
       return "cake"

Now, to evaluate if this approach is useful, let's ask the following questions:

Can you, upon seeing a Kitchen, and any specific Recipe implement another Recipe?
How much documentation do you need to read to make a new Recipe?
Can you add new items to cook, even if the cooking technique doesn't fall into the two categories (cook and bake)?
Does the interface force you to use it as it is designed? (as opposed to taking all items out of a Kitchen and then putting in a cooked item)

If you have a bunch of related methods, sometimes you don't need a comment to say they are related, you have an interface that you aren't coding like an interface. For example, you could have easily done a cook and a bake set of methods, taking parameters. While that might satisfy the rules of English more nicely, it doesn't actually add functionality, and it is a less effective design because you then have the option of using the wrong interface.