Javadoc wie viel sollte man erklären?

Dieses Thema im Forum "Programmierung" wurde erstellt von JTK222, 10. Mai 2015.

  1. JTK222
    Offline

    JTK222

    Registriert seit:
    5. September 2013
    Beiträge:
    665
    Ort:
    Planet Erde
    Minecraft:
    JTK222
    Hallo,

    ich arbeite seit längerem an einem Mod und habe diesen seit längerem auch schon auf Github zugänglich gemacht.
    Nun möchte ich auch Javadoc hinzufügen, nun das Problem ich habe sowas noch nie gemacht und hätte da einige fragen auf dem Gebiet.
    1.Gibt es hilfreiche Kürzel die unter vielen Java Programmierern bekannt sind?
    2.Sollte man es genau erklären damit neulinge dies auch als Tutorial nutzen können
    oder doch eher grob das nur jemand es versteht der sich damit auskennt?

    Ja frage 2 ist zwar eher eine frage der eigenen Meinung jedoch würde ich gerne wissen
    was ihr bevorzugt wenn ihr euch beispielsweise den Quellcode von einem Programm anschaut.

    3. Wie würdet ihr den unten angefügten Code mit Dokumentation bewerten?
    4. Eine frage die mit dem Rest nicht viel zu tun hat aber wie kann ich ohne ArrayList mehrere werte bei einer Methode zurück geben z.B. 2 Integer?
    (Müsste den Switch für das Alignment von unten in mehreren verschiedenen Methoden nutzen)
    Code (Text):
    1.  
    2. @SubscribeEvent(priority = EventPriority.NORMAL)
    3.     public void onRenderHealtheBar(RenderGameOverlayEvent event)
    4.     {
    5.         if(loadConfig.DRPGui == true){
    6.             if(event.type == event.type.HEALTH){
    7.                
    8.                 /**
    9.                 * Creating all needed Variables
    10.                 */
    11.                
    12.                 int currentHealth = (int) (79 * ( mc.thePlayer.getHealth()/mc.thePlayer.getMaxHealth()));
    13.                
    14.                 int posX = 0;
    15.                 int posY = 0;
    16.                
    17.                 List healthBarStats = loadConfig.HealthBar;
    18.                
    19.                 Integer Type = (Integer) healthBarStats.get(0);
    20.                
    21.                 Enum_GuiAlignment Alignment = (Enum_GuiAlignment) healthBarStats.get(1);
    22.                
    23.                 Integer PosX = (Integer) healthBarStats.get(2);
    24.                
    25.                 Integer PosY = (Integer) healthBarStats.get(3);
    26.                
    27.                 Boolean NumericHealth = (Boolean) healthBarStats.get(4);
    28.                
    29.                 /**
    30.                 * Setting the Main Coordinates for the Alignment
    31.                 */
    32.                 switch(Alignment){
    33.                 case BOTTOM:
    34.                     posX = event.resolution.getScaledWidth() / 2 -40;
    35.                     posY = event.resolution.getScaledHeight()-9;
    36.                     break;
    37.                 case LEFT:
    38.                     posX = 0;
    39.                     posY = event.resolution.getScaledHeight() / 2 - 4;
    40.                     break;
    41.                 case RIGHT:
    42.                     posX = event.resolution.getScaledWidth() - 81;
    43.                     posY = event.resolution.getScaledHeight() / 2 -4;
    44.                     break;
    45.                 case TOP:
    46.                     posX = event.resolution.getScaledWidth()/2 -40;
    47.                     posY = 0;
    48.                     break;
    49.                 case CENTER:
    50.                     posX = event.resolution.getScaledWidth()/2 -40;
    51.                     posY = event.resolution.getScaledHeight()/2 -4;
    52.                     break;
    53.                 case TOPLEFT:
    54.                     posX = 0;
    55.                     posY = 0;
    56.                     break;
    57.                 case TOPRIGHT:
    58.                     posX = event.resolution.getScaledWidth() -81;
    59.                     posY = 0;
    60.                     break;
    61.                 case BOTTOMLEFT:
    62.                     posX = 0;
    63.                     posY = event.resolution.getScaledHeight()-9;
    64.                     break;
    65.                 case BOTTOMRIGHT:
    66.                     posX = event.resolution.getScaledWidth()-81;
    67.                     posY = event.resolution.getScaledHeight()-9;
    68.                     break;
    69.                 default:
    70.                     posX = event.resolution.getScaledWidth() / 2 -40;
    71.                     posY = event.resolution.getScaledHeight()-9;
    72.                     break;
    73.                 }
    74.                
    75.                 /**
    76.                 * Adding the user set Coordinates of the Health bar to the Alignment Coordinates
    77.                 */
    78.                 posX = posX + PosX;
    79.                 posY = posY + PosY;
    80.                
    81.                 /**
    82.                 * Binding the Texture File will be made using a switch in future versions because of different Gui Types
    83.                 */
    84.                 this.mc.getTextureManager().bindTexture(texturepath);
    85.                 GL11.glEnable(GL11.GL_BLEND);
    86.                 GL11.glBlendFunc(GL11.GL_SRC_ALPHA, GL11.GL_ONE_MINUS_SRC_ALPHA);
    87.                
    88.                 this.drawTexturedModalRect(posX, posY, 0, 16, 81, 9);
    89.                
    90.                
    91.                 /**
    92.                 * Drawing the Health and also a Potion effect that affects the Health if one is existing
    93.                 */
    94.                 this.drawTexturedModalRect(posX +1, posY +1, 0, 25, currentHealth,7);
    95.                
    96.                 if((int)mc.thePlayer.getAbsorptionAmount() != 0){
    97.                     this.drawTexturedModalRect(posX+1, posY +1, 0, 32, currentHealth,7);
    98.                 }
    99.                 if(mc.thePlayer.isPotionActive(Potion.poison)){
    100.                     this.drawTexturedModalRect(posX+1, posY +1, 0, 39, currentHealth,7);
    101.                 }
    102.                 if(mc.thePlayer.isPotionActive(Potion.wither)){
    103.                     this.drawTexturedModalRect(posX+1, posY +1, 0, 46, currentHealth,7);
    104.                 }
    105.                
    106.                 /**
    107.                 * Writing the Health Amount in Numbers to the Health Bar.
    108.                 * The bottom one is used by default the upper one is for the case that the player has additional health.
    109.                 * (For example you get additional health when you eat an Enchanted Golden Apple)
    110.                 */
    111.                 if(NumericHealth){
    112.                    
    113.                     if((int)mc.thePlayer.getAbsorptionAmount() > 0 ){
    114.                         healthDisplay = (int)mc.thePlayer.getHealth() + "/" +(int) mc.thePlayer.getMaxHealth() + "+" + (int) mc.thePlayer.getAbsorptionAmount();
    115.                     }else{
    116.                         healthDisplay = (int)mc.thePlayer.getHealth() + "/" +(int) mc.thePlayer.getMaxHealth();
    117.                     }
    118.                    
    119.                     this.mc.fontRendererObj.drawString(healthDisplay, posX+40 - (healthDisplay.length()*3), posY+1, 0xffFFFFFF);
    120.                 }
    121.                 /**
    122.                 * Setting the used Texture back to Minecrafts default one (otherwise Breath bar and the other stuff would use the wrong texture File)
    123.                 */
    124.                 this.mc.getTextureManager().bindTexture(new ResourceLocation("textures/gui/icons.png"));
    125.                
    126.                 /**
    127.                 * Canceling the Event so the default Health bar isn't rendered.
    128.                 */
    129.                 event.setCanceled(true);
    130.             }
    131.         }
    132.     }
    133.  
    Vielen Dank im Voraus.
    - JTK222
     
    #1
  2. [Dev] iTzSasukeHDxLP
    Offline

    [Dev] iTzSasukeHDxLP Ehem. Teammitglied

    Registriert seit:
    5. Januar 2014
    Beiträge:
    938
    Hey,

    ein beispiel:
    Code (Javascript):
    1. /**
    2.      * Sets the score of the given player
    3.      *
    4.      * @param player The player whose score is to set
    5.      * @param value  The value to set the score to
    6.      */
    7.     public void setScore( Player player, int value ) {
    Normalerweise reicht eine kurze Zeile über Sinn und Funktion der Methode, sowie eine Beschreibung der Parameter. Optional kommen dann auch eine Beschreibung des Objektes hinzu, die eine Methode (evtl.) zurückgibt. Hinweise auf Exceptions sind auch immer ganz sinnvoll. Du hast sehr viel innerhalb der Methode erklärt, da würde ich zwecks übersichtlichkeit mit single line ( '//' ) dokumentieren.

    Natürlich gibt es auch Kürzel, aber da sind die meisten leute ziemlich eigen. Hilfreich sind allerdings Verlinken zu den Sourceklassen und so weiter.

    Alternativen zu einer ArrayList sind Arrays, Sets oder Maps. Wenn du allerdings mehrere Sachen zurückgeben möchtest kommst du um irgendeine Art der Collection bzw. ein Array nicht drumherum.



    Wenn ich mir Sourcecode angucken möchte, verschaffe ich mir zu allererst eine Übersicht über die Aufteilung der Klassen und Packages und arbeite mich dann aus der Hauptklasse in alle Unterbereiche vor.
     
    #2
    JTK222 gefällt das.
  3. JTK222
    Offline

    JTK222

    Registriert seit:
    5. September 2013
    Beiträge:
    665
    Ort:
    Planet Erde
    Minecraft:
    JTK222
    Vielen dank für die paar Tipps habe an einiges hiervon nicht gedacht (also @param und so :))
    Auch danke für den Vorschlag mit bei einzelnen Zeilen mit // zu arbeiten habe ich total vergessen :D

    Ist für die Rückgabe von mehreren werten pro Methode irgendetwas besonders empfehlenswert?
    Falls nicht werde ich es ganz einfach mit einer ArrayList regeln.

    P.s. was meinst du mit Verlinkung zu den Source Classen und wie kann ich diese erstellen?
     
    #3
  4. Heldin
    Offline

    Heldin

    Registriert seit:
    22. April 2015
    Beiträge:
    42
    #4