Comment your damn code bitch

Voilà ce que j’ai essayé d’expliquer à un collègue quand il m’a dit que mon code ne comportait pas de commentaires

    def kos_root(self):
        """Return the pathname of the KOS root directory."""
        if self._kos_root: 
            return self._kos_root
    ...
    def kos_root(self):
        """Return the pathname of the KOS root directory."""
        if self._kos_root: 
            return self._kos_root
        #bug 3154   - 04/25/2009
        else: 
            return 0 

Tu peux voir comment ta méthode a été testée. Les tests sont à jour:

    class TestMain(unittest.TestCase):

        def setUp(self):
            self.main = Main()

        def test_kos_root(self):
            self.assertTrue(self.main.kos_root())

        def test_false_kos_root_should_return_zero(self):
            self.main._kos_root = False
            self.assertEqual(0, self.main.kos_root())

Pour résumer, le code d’un logiciel ne doit pas comporter de commentaires, c’est un aveu d’échec sur sa capacité à rendre son code explicite. Son code doit refléter précisément son intention lors de sa conception. Et la documentation ce sont les tests. Ils doivent être à jour, et chaque bug doit comporter un test de non régression.

Ps: cette conversation n’est que pure fiction