为什么我应该“谨慎使用内联注释”?

时间:2019-03-23 00:57:26

标签: python python-3.x annotations comments

阅读PEP8(https://www.python.org/dev/peps/pep-0008/#comments),我发现程序员应该“谨慎使用内联注释”。不过,没有提供任何理由。

我想知道为什么。我真的发现通过内联注释阅读代码更容易理解程序,这样我在尝试阅读和理解代码时就不会被注释打扰。

最好的情况是,使注释与我们在Word中一样,与代码中的特定点匹配,但仅在侧面板中可见。我不知道是否有具有此类功能的IDE。

话虽这么说,问题是

  1. 是否存在诸如性能下降之类的技术原因,而不是内联而不是内联?

  2. 阅读我的代码的人会为许多内联注释感到生气吗,或者这没什么大不了的,前提是这些注释确实有用。

  3. 是否有一个具有更好注释环境的IDE?可能是侧面板,可能是与.py文件绑定的.txt文件,并通过其UI显示这些注释。 Idk,什么都可以。

阅读PEP,Python文档并尝试对其进行谷歌搜索。没有有用的答案。

(很抱歉,太糟糕了。有点像Python 3的初学者。)

guessed_char = len(secret_word)*["_ "]  #  Defines varLIST of STRs, masked version of
                                        #  secret_word, and also the progression
                                        #  shown to the player

answer = len(secret_word)*[""]          #  Defines varLIST of STRs, that will be checked
                                        #  against secret_word (varSTR) through
                                        #  "".join(answer)

guessed_attempts = []                   #  Defines varLIST of STRs, that will store
                                        #  every letter guessed by the player.

enforcou = False                        #  Defines varBOOL, turns True if attempts
                                        #  (varINT) reaches the limit. Ends the game
                                        #  with a loss.

acertou = False                         #  Defines varBOOL, turns True if word is
                                        #  found by player. Ends the game with a win.

pontos = int(100)                       #  Defines varINT, counts points that will be
                                        #  deduced at every failend attempt.Every
                                        #  change to this value must be followed by
                                        #  changes in other parts of this code

                                        #  Asks player for difficulty level
print("Qual nível de dificuldade?\n 1 - 3 tentativas\n 2- 5 tentativas\n 3 - 10 tentativas")
dificuldade = int(input())
if (dificuldade == 1):
    max_attempts = 3                    #  Define varINT, total number of attempts
elif (dificuldade == 2):
    max_attempts = 5                    #  Define varINT, total number of attempts
else:
    print("Vamos jogar no fácil...")
    max_attempts = 10                   #  Define varINT, total number of attempts

attempts = 1                            #  Define varINT, counts the number of attempts

print("".join(guessed_char))            #  Prints the masked version of secret_word
                                        #  (varSTR) that the player is trying to guess

while (not enforcou and not acertou):   #  Conditions for ending the game.

    print(f"Tentativa {attempts} de {max_attempts}") #  Tells player the attempt number

    guess = input("Qual letra? ").lower()   #  Asks for a guess (varSTR)

    guessed_attempts.append(guess)      #  Adds the guess to the guess' storage

    if (guess in secret_word):          #  If the guess is correct

        index = 0                       #  Defines varINT for storing indexes

        for char in secret_word.lower():    #  iterate through every character in
                                            #  secret_word (varSTR)

            if (guess == char):         #  If the guess matches the character

                guessed_char[index] = f"{guess} "   #  Replaces dummy "_ " in
                                                    #  guesed_char (varLIST)
                                                    #  revealling guessed characters
                                                    #  in the masked progresion shown
                                                    #  to the player

                answer[index] = f"{guess}"          #  Replaces dummy with answer

                print(f"Encontrei a letra {char} na posiçao {index}")   #  Prints that something was correct
                print("".join(guessed_char))        #  Prints the update masked word
                pontos += round(100/max_attempts)   #  Adds points
                if("".join(answer) == secret_word): #  Checks if the player won
                    acertou = True                  #  End while cicle if player won
                    print(f"Você ganhou! A palavra era '{secret_word}'!")   #Prints message telling player he/she won
            index += 1                     #  Adds 1 to varINT index, so everything is on track
    else:                                  #  If guess is not correct
        pontos -= round(100/max_attempts)   # Subtracts points
        print("Que pena, você errou...")    #Tells player he missed
        print("".join(guessed_char))        # Print masked word
                                            # Tells player the guesses he already tried, with correct grammar for linstings in portuguese
        print("Você já tentou as letras ", ", ".join(str(e) for e in guessed_attempts[:-1]), " e ", guessed_attempts[-1], ".", sep="")
        attempts += 1                       # Adds 1 to varINT attempts, so the game get closer to end due to loss
    enforcou = attempts == max_attempts+1   # Defines coditions for losing the game
if (enforcou):                              # If losing conditions are met
    print(f"Que pena, você perdeu... A palavra era '{secret_word}'...")    # Print loss message and the word
print(f"Você fez {pontos} pontos.") # Prints the number of points, regardless of winning or losing.
print ("Fim do jogo") # Tells the player the game ended.

1 个答案:

答案 0 :(得分:0)

我认为反对内联注释的一个简单原因是最大行长为79个字符https://www.python.org/dev/peps/pep-0008/#id17,因此您不想将代码过多地包裹以适合内联注释。

您还可以通过其他方式添加注释,例如文档字符串(https://www.python.org/dev/peps/pep-0257/),该注释可能涵盖了变量的作用。