Ana akım, burada diğer cevapların da belirttiği gibi, muhtemelen Sfenks yoluyla gitmek, böylece daha sonra bu süslü belgeleri oluşturmak için Sfenks'i kullanabilirsiniz.
Olduğu söyleniyor, ben zaman zaman satır içi yorum stili ile şahsen gidiyorum.
def complex( # Form a complex number
real=0.0, # the real part (default 0.0)
imag=0.0 # the imaginary part (default 0.0)
): # Returns a complex number.
"""Form a complex number.
I may still use the mainstream docstring notation,
if I foresee a need to use some other tools
to generate an HTML online doc later
"""
if imag == 0.0 and real == 0.0:
return complex_zero
other_code()
Burada bir örnek daha, bazı küçük ayrıntılar satır içi olarak belgelenmiştir:
def foo( # Note that how I use the parenthesis rather than backslash "\"
# to natually break the function definition into multiple lines.
a_very_long_parameter_name,
# The "inline" text does not really have to be at same line,
# when your parameter name is very long.
# Besides, you can use this way to have multiple lines doc too.
# The one extra level indentation here natually matches the
# original Python indentation style.
#
# This parameter represents blah blah
# blah blah
# blah blah
param_b, # Some description about parameter B.
# Some more description about parameter B.
# As you probably noticed, the vertical alignment of pound sign
# is less a concern IMHO, as long as your docs are intuitively
# readable.
last_param, # As a side note, you can use an optional comma for
# your last parameter, as you can do in multi-line list
# or dict declaration.
): # So this ending parenthesis occupying its own line provides a
# perfect chance to use inline doc to document the return value,
# despite of its unhappy face appearance. :)
pass
Avantajları (@ mark-horvath'in başka bir yorumda zaten belirttiği gibi):
- En önemlisi, parametreler ve onların dokümanı her zaman birlikte kalır, bu da aşağıdaki faydaları sağlar:
- Daha az yazma (değişken adını tekrarlamaya gerek yoktur)
- Değişken değiştirildikten / çıkarıldıktan sonra daha kolay bakım. Bazı parametreleri yeniden adlandırdıktan sonra hiçbir zaman yetim parametresi doc paragrafı olmayacaktır.
- ve eksik yorumu bulmak daha kolay.
Şimdi, bazıları bu tarzın "çirkin" göründüğünü düşünebilir. Ama "çirkin" in öznel bir kelime olduğunu söyleyebilirim. Daha nötr bir yol, bu tarzın ana akım olmadığını, bu yüzden size daha az tanıdık görünebileceğini, dolayısıyla daha az rahat olabileceğini söylemektir. Yine "rahat" aynı zamanda öznel bir kelimedir. Ancak mesele, yukarıda açıklanan tüm faydaların nesnel olmasıdır. Standart yolu izlerseniz onlara ulaşamazsınız.
Umarım gelecekte bir gün, böyle bir satır içi stilini de tüketebilen bir doktor oluşturma aracı olacaktır. Bu benimsemeyi yönlendirecektir.
Not: Bu cevap, uygun gördüğümde satır içi yorumları kullanma tercihimden kaynaklanıyor. Bir sözlüğü de belgelemek için aynı satır içi stilini kullanıyorum .