{"id":21,"date":"2021-04-14T08:03:00","date_gmt":"2021-04-14T08:03:00","guid":{"rendered":"https:\/\/webdevs.blog\/pl\/?p=21"},"modified":"2026-02-20T07:28:27","modified_gmt":"2026-02-20T07:28:27","slug":"komentarze-w-kodzie-czy-i-w-jaki-sposob-je-pisac","status":"publish","type":"post","link":"https:\/\/webdevs.blog\/pl\/komentarze-w-kodzie-czy-i-w-jaki-sposob-je-pisac\/","title":{"rendered":"Komentarze w kodzie – Czy i w jaki spos\u00f3b je pisa\u0107?"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n
\n
\n

Prawid\u0142owe zastosowanie komentarzy jest kompensowaniem naszych b\u0142\u0119d\u00f3w przy tworzeniu kodu. (\u2026) Obecno\u015b\u0107 komentarzy zawsze sygnalizuje nieporadno\u015b\u0107 programisty. Musimy z nich korzysta\u0107, poniewa\u017c nie zawsze wiemy jak wyrazi\u0107 nasze intencje bez ich u\u017cycia, ale ich obecno\u015b\u0107 nie jest powodem do \u015bwi\u0119towania.<\/em><\/p>\nRobert C. Martin – Czysty kod<\/cite><\/blockquote>\n<\/div>\n\n\n\n

Kr\u00f3tki cytat z jednej najbardziej popularnych ksi\u0105\u017cek traktuj\u0105cych o praktykach tworzenia dobrego oprogramowania, w du\u017cym stopniu odzwierciedla problem jakim jest prze\u0142adowanie kodu komentarzami. Wykorzystujemy je aby uzasadni\u0107 pewnego rodzaju lenistwo, brak czasu, albo po prostu ch\u0119\u0107 pisania du\u017cej ilo\u015bci kodu, kt\u00f3ra w ostateczno\u015bci okazuje si\u0119 z\u0142udnym sukcesem.<\/p>\n\n\n

\/\/ Checking if the employee should get the bonus<\/span>\nif<\/span> ($employee->age > 65<\/span> && $employee->status === 'active'<\/span>) {}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n
if<\/span> ($employee->isEligibleForBonus()) {}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Analizuj\u0105c powy\u017cszy przyk\u0142ad, mo\u017cemy zauwa\u017cy\u0107, \u017ce kod wyglada zdecydowanie schludniej je\u015bli zamiast niejasnego warunku wykorzystamy czyteln\u0105 funkcj\u0119, kt\u00f3rej sama nazwa zniweluje potrzeb\u0119 t\u0142umaczenia o co chodzi.<\/p>\n\n\n\n
\n\n\n\n
B\u0142\u0119dne Komentarze<\/h2>\n\n\n\n
Paplanina<\/h3>\n\n\n\n
Nie wyja\u015bniaj rzeczy, kt\u00f3re s\u0105 ju\u017c jasne.<\/p>\n\n\n\n
Niepoprawnie<\/h6>\n\n\n
\/**\n * @var<\/span> Product Product object;\n *\/<\/span>\nprivate<\/span> Product $product;\n\n\/**\n * Function returns the price that is loaded from the product object bla bla bla.\n *\/<\/span>\npublic<\/span> function<\/span> getProductPrice<\/span>()<\/span> <\/span>{\n    return<\/span> $this<\/span>->product->getPrice();\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Poprawnie<\/h6>\n\n\n
private<\/span> Product $product;\n\npublic<\/span> function<\/span> getProductPrice<\/span>()<\/span>: int<\/span> <\/span>{\n    return<\/span> $this<\/span>->product->getPrice();\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Doc Blocks<\/h3>\n\n\n\n
Nie umieszczaj niepotrzebnych informacji w komentarzach blokowych.<\/p>\n\n\n\n
Poni\u017cszy przyk\u0142ad kalkuluje finaln\u0105 cen\u0119, kt\u00f3ra jest wynikiem mno\u017cenia buforu oraz wska\u017anika ryzyka. Ale co dok\u0142adnie jest \u017ale?<\/p>\n\n\n\n
Niepoprawnie<\/h6>\n\n\n
\/**\n * Function returns the final price.\n * @param<\/span> int $a Total price.\n * @param<\/span> int $b Buffer miltiplier.\n * @param<\/span> int $c Risk miltiplier.\n * @return<\/span> int Final price.\n *\/<\/span>\npublic<\/span> function<\/span> getPrice<\/span>($a, $b, $c)<\/span> <\/span>{\n    return<\/span> $a * $b * $c;\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
\n
1. Nale\u017cy wyja\u015bni\u0107 znaczenie argument\u00f3w funkcji, poniewa\u017c s\u0105 domy\u015blnie niezrozumia\u0142e. 
2. Nazwa funkcji informuje o tym, \u017ce zwracana jest *jaka\u015b* cena, a dok\u0142adne wyja\u015bnienie czym ona jest znajduje si\u0119 w komentarzu. 
3. Informujemy o typach komentarzu blokowym maj\u0105c mo\u017cliwo\u015b\u0107 wykorzystania typ\u00f3w argument\u00f3w.<\/p>\n\n\n\n
Poprawnie<\/h6>\n\n\n
public<\/span> function<\/span> getFinalPrice<\/span>(int $totalPrice, int $bufferMultiplier, int $riskMultiplier)<\/span>: int<\/span> <\/span>{\n  return<\/span> $totalPrice * $bufferMultiplier * $riskMultiplier;\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre><\/div>\n\n\n\n
1. Poprawne nazewnictwo argument\u00f3w jednoznacznie wyja\u015bni\u0142o ich znaczenie. 
2. Dok\u0142adna nazwa funkcji zniwelowa\u0142a potrzeb\u0119 wyja\u015bnienia dzia\u0142ania poprzez komentarz. 
3. Wykorzystanie typ\u00f3w r\u00f3wnie\u017c wyeliminowa\u0142o potrzeb\u0119 pozostawienia komentarza.<\/p>\n\n\n\n
Punkt 3 zale\u017cy od projektu, ale wymaganie te musi by\u0107 spe\u0142nione je\u015bli mamy mo\u017cliwo\u015b\u0107 pracy z j\u0119zykiem wspieraj\u0105cym typy i nie przejmujemy si\u0119 systemami automatycznie generuj\u0105cymi dokumentacje.<\/p>\n\n\n\n
Author<\/h3>\n\n\n\n
Nie informuj o autorze w komentarzu blokowym.<\/p>\n\n\n\n
Niepoprawnie<\/strong><\/h6>\n\n\n
\/**\n * @author<\/span> PH\n *\/<\/span>\nclass<\/span> Product<\/span> <\/span>{\n    \/**\n    * @author<\/span> PH\n    *\/<\/span>\n    public<\/span> function<\/span> getPrice<\/span>()<\/span> <\/span>{}\n\n    \/**\n    * @author<\/span> PH\n    *\/<\/span>\n    public<\/span> function<\/span> getName<\/span>()<\/span> <\/span>{}\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Poprawnie<\/h6>\n\n\n
class<\/span> Product<\/span> <\/span>{\n    public<\/span> function<\/span> getPrice<\/span>()<\/span> <\/span>{}\n\n    public<\/span> function<\/span> getName<\/span>()<\/span> <\/span>{}\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Jak w takim wypadku pozna\u0107 autora?<\/p>\n\n\n\n
1. Wykorzystaj GitLens – https:\/\/marketplace.visualstudio.com\/items?itemName=eamodio.gitlens 
2. Wykorzystaj git blame – https:\/\/gitbetter.substack.com\/p\/how-to-use-git-blame-effectively. 
3. Wykorzystaj github.com \/ bitbucket.com aby sprawdzi\u0107 kto edytowa\u0142 plik.<\/p>\n\n\n\n
Notatki<\/h3>\n\n\n\n
Nie pozostawiaj w kodzie niepotrzebnych adnotacji.<\/p>\n\n\n
\/\/ Done by Andrew<\/span>\n$test = ''<\/span>;<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Kod<\/h3>\n\n\n\n
Nie pozostawiaj niepotrzebnego kodu.<\/p>\n\n\n
\/\/ public function getPrice($a, $b, $c) {<\/span>\n\/\/     return $a * $b * $c;<\/span>\n\/\/ }<\/span><\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
Komentarze akceptowalne<\/h2>\n\n\n\n
TODO<\/h3>\n\n\n\n
Czasami dobrym pomys\u0142em jest umieszczenie komentarzy @todo<\/code> w celu poinformowania o zamierzeniach, albo wa\u017cnych elementach, kt\u00f3re zostan\u0105 zmienione w przysz\u0142o\u015bci.<\/p>\n\n\n
\/**\n * @todo<\/span> Remove when XY will be ready.\n *\/<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Konsekwencje<\/h3>\n\n\n\n
Je\u015bli kod tego wymaga, umie\u015b\u0107 informacje o konsekwencjach w celu ostrze\u017cenia innego dewelopera.<\/p>\n\n\n
\/**\n * This function will burn your machine.\n *\/<\/span>\npublic<\/span> function<\/span> importData<\/span>()<\/span>: void<\/span> <\/span>{}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Wyja\u015bnienia<\/h3>\n\n\n\n
Je\u015bli sytuacja tego wymaga – np. przez brak bud\u017cetu – umie\u015b\u0107 komentarz wyja\u015bniaj\u0105cy istnienie danego rozwi\u0105zania.<\/p>\n\n\n
\/**\n * Function fixes the problem with FacetWP and Postfinance plugin.\n *\n * Symptoms:    The FacetWP plugin doesn\u2019t work correctly when the Access plugin is also active. For example, if you add a custom\n *              search and try to filter by taxonomy, the FacetWP filter is ignored and a full list of posts is rendered. The issue\n *              is actually caused by the FacetWP plugin, which is running the init filter before everything else.\n *\n *              If you use FacetWP while Access is active basically all FacetWP\u2019s AJAX-based features like search results and pagination will fail.\n *\n * Workaround:  FacetWP modifies the Main Query with additional parameters and runs another WP_Query instance to show search results.\n *              Here is a short explanation of what happens:\n *\n *              - When Toolset Access tries to check\/set permissions for the Custom Post Types, it runs the toolset_access_get_current_page_id\n *                function that, in turn, runs the url_to_postid WordPress core function.\n *              - That url_to_postid function runs another WP_Query that replaces the result from the FacetWP\u2019s query and completely breaks the\n *                results from FacetWP.\n *\n *              This happens because of the late priority of Access and the early priority of FacetWP.\n *\n * Fix:         Theme tells the plugin that the payment page is the one with `woo_postfinancecw` slug.\n *\n * @filter<\/span> woocommerce_postfinancecw_is_plugin_page\n * @see<\/span> https:\/\/toolset.com\/errata\/compatibility-issue-between-facetwp-and-access-plugins\/\n *\/<\/span>\npublic<\/span> function<\/span> fixFilters<\/span>()<\/span>: bool<\/span>\n<\/span>{\n  global<\/span> $wp;\n  return<\/span> 'woo_postfinancecw'<\/span> === $wp->request;\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Nie znaczy to, \u017ce powiniene\u015b umieszcza\u0107 takie komentarze w ka\u017cdym jednym miejscu w kodzie, kt\u00f3re wydaje si\u0119 skomplikowane. Zawsze powiniene\u015b podchodzi\u0107 do tego tematu ostro\u017cnie wcze\u015bnie potwierdzaj\u0105c, \u017ce nie zostaje Ci nic innego.<\/p>\n\n\n\n
\n\n\n\n
Kilka regu\u0142 wystarczy, aby znacznie odchodzi\u0107 kod. Najwa\u017cniejsze w tym wszystkim jest to, aby rozumnie podchodzi\u0107 do wykorzystania komentarzy.<\/p>\n\n\n\n
Za ka\u017cdym razem gdy napisa\u0142e\u015b komentarz, przeczytaj go jeszcze raz krok po kroku czytaj\u0105c r\u00f3wnie\u017c kod. W wielu przypadkach w tym tek\u015bcie wy\u0142oni\u0105 si\u0119 od razu nazwy funkcji, na kt\u00f3re z pewno\u015bci\u0105 mo\u017cna rozbi\u0107 skomentowan\u0105 funkcj\u0119.<\/p>\n\n\n","protected":false},"excerpt":{"rendered":"
Prawid\u0142owe zastosowanie komentarzy jest kompensowaniem naszych b\u0142\u0119d\u00f3w przy tworzeniu kodu. (\u2026) Obecno\u015b\u0107 komentarzy zawsze sygnalizuje nieporadno\u015b\u0107 programisty. Musimy z nich korzysta\u0107, poniewa\u017c nie zawsze wiemy jak wyrazi\u0107 nasze intencje bez ich u\u017cycia, ale ich obecno\u015b\u0107 nie jest powodem do \u015bwi\u0119towania. Kr\u00f3tki cytat z jednej najbardziej popularnych ksi\u0105\u017cek traktuj\u0105cych o praktykach tworzenia dobrego oprogramowania, w du\u017cym […]<\/p>\n","protected":false},"author":6,"featured_media":22,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[30,31],"class_list":["post-21","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dobre-praktyki","tag-code-comments","tag-doc-blocks"],"_links":{"self":[{"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/posts\/21","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/users\/6"}],"replies":[{"embeddable":true,"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/comments?post=21"}],"version-history":[{"count":4,"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/posts\/21\/revisions"}],"predecessor-version":[{"id":717,"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/posts\/21\/revisions\/717"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/media\/22"}],"wp:attachment":[{"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/media?parent=21"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/categories?post=21"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/webdevs.blog\/pl\/wp-json\/wp\/v2\/tags?post=21"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}