Codestyle

Váš kód, který budete v rámci předmětu tvořit musí být v souladu s PEP8.

V reálném světě musíte respektovat codestyle definovaný firmou kde pracujete, nebo daný projektem, na kterém se podílíte. Pokud pythonem začínáte, naučte se psát pythonový kód rovnou správně, i když to bude občas opruz.

U domácích úkolů je to kontrolováno automaticky pomocí pylint v unit-testech.
Pro vlastní ověření využijte buď vaše IDE, nebo např.: pycodestyle ./ nebo pylint ./yourcode.py --disable=C0301,C0103, nebo se inspirujte testy z domácích úkolů.
- Ale pozor, v semestrálce jasně vyznačte, co je a co není váš vlastní kód!

Všeobecnou výjimku (pro úkoly i semestrálky) z dodržování PEP8 mají dlouhé řádky (C0301) a krátké názvy proměnných (C0103). Myslíme si, že v době širokoúhlých monitorů je požadavek na 79 znaků na řádek poněkud extrémem; a že kratší kód obvykle bývá čitelnější.

U některých domácích úkolů je tolerováno ještě nesplnění následujicích pravidel:

příliš mnoho lokálních proměnných (R0914)
příliš mnoho argumentů funkce (R0913)
příliš obecná výjimka (W0719) - abyste nemuseli dělat vlastní třídu dědící z Exception
no-member (E1101) - pokud je to v balíčku/modulu 3. strany

Pro detaily prozkoumejte testy, hledejte u metody linter. Tyto další výjimky už ale neplatí pro kód vašich semestrálních prací! Někdy se tomu nesouladu v rámci SP nedá vyhnout (například při použití knihovny 3. strany – příklad za všechny: pygame) a v takovém případě neřešte nesoulad s PEP8 v kódu 3. strany.

Užitečné příkazy pro kontrolu codestyle

Rychlý přehled:

pycodestyle --statistics -qq ./ případně neagregované, že vidíte, kde přesně je chyba: pycodestyle ./

Detailní přehled:

pylint --disable=C0301,C0103 -sn ./code.py

Pro celý projekt rekurzivně:

find . type f -name "*.py" | xargs pylint --disable=C0301,C0103 -sn

Anotace / tagování generovaných částí kódu

S rozvojem LLM a nástroji jako chatGPT, GitHub Copilot, Gemini, Bard a další se zcela přirozeně v rámci odevzdávaného kódu (ať už v úkolech nebo hlavně v semestrálkách) objevují části, které generoval nějaký jazykový model či obdobný nástroj.

V souladu s interním předpisem ČVUT: Rámcová pravidla používání umělé inteligence na ČVUT pro studijní a pedagogické účely v Bc a NM studiu je možné nástroje pro generování kódu využít. U domácích úkolů to spíš nedoporučujeme kvůli riziku přílišné podobnosti (viz Hodnocení úkolů). U semestrální práce klidně ano, ale s rozvahou.

Každopádně od vás ale budeme vyžadovat, abyste generovaný kód důsledně označovali. Zatím na to není jednotný standart, takže v rámci pilotního testování vycházíme z návrhů 1 a 2. Vaší povinností bude označit všechny byť částečně generované bloky kódu na úrovni funkce, třídy, případně modulu pomocí strojově zpracovatelného jednořádkového komentáře:

# @generated "[MEASURE]" TOOL-WITH-VERSION: [ANOTHER-COMMENT-MAY-BE-TRIMMED-PROMPT]

Kde:

MEASURE nabývá jedné z hodnot: all | partially. Neoznačené bloky budou považovány výhradně za lidský výtvor.
TOOL-WITH-VERSION je string identifikující použitý nástroj a jeho verzi
ANOTHER-COMMENT-MAY-BE-TRIMMED-PROMPT je volitelný string blíže vysvětlující okolnosti. Může se jednat o váš komentář například, že generovaná je jen funkce XYZ v rámci třídy, nebo třeba prompt poskytnutý LLM (podle potřeb rozumně oříznutý na cca prvních 100 znaků).

Granularitu (tedy zda oanotujete funkci, třídu nebo celý modul) volte dle svého vlastního svědomí a míry využití generativního nástroje. Pokud vám nástroj vygeneroval celou třídu a nemuseli jste do ní zasahovat, anotujte třídu. Pokud jste si jen nechali poradit s třídícím algoritmem, nabízí se anotovat jen funkci v níž je implementován.

Nechceme vás nutit úplně zaplevelit kód u každé funkce dalšími komentáři, ani to vždy neodbývejte na úrovni modulu. Budeme to průběžně vyhodnocovat a možná se časem (v dalších semestrech) požadavky upraví.

Příklady anotací

Na úrovni funkce a třídy:

# @generated [all] GitHub Copilot o1:
def foo(bar):
  pass

# @generated [partially] Gemini 2.0: jen konstruktor, zbytek psal clovek
class Foo:
  def __init__(self):
    pass
  def abc(self):
    pass
  def def(self):
    pass

Na úrovni modulu:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# @generated [partially] chatGPT 2025-01-31: prompt: dopln docstringy v kodu, cesky bez diakritiky...
"""
Created on Sun Mar 17 10:10:10 2036
@author: John Doe
"""

from datetime import timedelta

def foo(bar):
  """
  Funkce zatim nic nedela a vyuziva pouze prazdny prikaz pass.
  """
  pass