From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id +L5FIcUqZGPF7wAAbAwnHQ (envelope-from ) for ; Thu, 03 Nov 2022 21:55:33 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id IKIsIMUqZGNvOQAAG6o9tA (envelope-from ) for ; Thu, 03 Nov 2022 21:55:33 +0100 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 550D529116 for ; Thu, 3 Nov 2022 21:55:32 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqhEW-0000Kg-IB; Thu, 03 Nov 2022 16:54:40 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oqhEU-0000JH-Ud for emacs-orgmode@gnu.org; Thu, 03 Nov 2022 16:54:38 -0400 Received: from ci74p00im-qukt09090501.me.com ([17.57.156.22]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oqhET-0001Lb-Fg for emacs-orgmode@gnu.org; Thu, 03 Nov 2022 16:54:38 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=me.com; s=1a1hai; t=1667508876; bh=HmhaU7Qj/lteFpLR4VsCG6mzigdgYWfb1KfcN4gy4cc=; h=From:To:Subject:Date:Message-ID:MIME-Version:Content-Type; b=EYqBs+PeaEtPQ7oGnomvagH6FC04j5NKwyvI7kxc/7v9ZdaKQjv/jPQG86qJjNhZn iFN7tdx3X+DNWmebQUNao0vljaz9wVp8c9zSDPSWW/L0joU7PLE2/JmoqQ3Z78eWAI rEHkEQdCtXVYPZGjgrPS9Sj89gHcFk+j+wFRptlD8Gfkm6PTpqsW0peqOjwgf+EIb2 PpHp41KWHn/2eiu2R0RhObafK3KO9Skqkyapr2g9qRcit5FgA/qDeyuAziAzsSqlvu 2tVn3rhyPXprY20ZsFMc/+F6PAa0J/eFS6FAInPjWep9GzoThga1ccCIo/coa0QGt2 Ay4/CGmQZra8w== Received: from Rudolfs-MacBook-Air.local (ci77p00im-dlb-asmtp-mailmevip.me.com [17.57.156.26]) by ci74p00im-qukt09090501.me.com (Postfix) with ESMTPSA id B8F934640486; Thu, 3 Nov 2022 20:54:34 +0000 (UTC) From: Rudolf =?utf-8?Q?Adamkovi=C4=8D?= To: Juan Manuel =?utf-8?Q?Mac=C3=ADas?= , orgmode Subject: Re: Docstrings and literate programming (good practices?) In-Reply-To: <87bkpqbwef.fsf@posteo.net> References: <87bkpqbwef.fsf@posteo.net> Date: Thu, 03 Nov 2022 21:54:32 +0100 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Proofpoint-GUID: t77-EhTiGX_laRqGlN3p4PdR6OKcVy4B X-Proofpoint-ORIG-GUID: t77-EhTiGX_laRqGlN3p4PdR6OKcVy4B X-Proofpoint-Virus-Version: =?UTF-8?Q?vendor=3Dfsecure_engine=3D1.1.170-22c6f66c430a71ce266a39bfe25bc?= =?UTF-8?Q?2903e8d5c8f:6.0.138,18.0.572,17.0.605.474.0000000_definitions?= =?UTF-8?Q?=3D2020-02-14=5F11:2020-02-14=5F02,2020-02-14=5F11,2020-01-23?= =?UTF-8?Q?=5F02_signatures=3D0?= X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 adultscore=0 malwarescore=0 spamscore=0 mlxlogscore=999 bulkscore=0 mlxscore=0 clxscore=1015 suspectscore=0 phishscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2209130000 definitions=main-2211030143 Received-SPF: pass client-ip=17.57.156.22; envelope-from=salutis@me.com; helo=ci74p00im-qukt09090501.me.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "Emacs-orgmode" Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1667508932; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=HmhaU7Qj/lteFpLR4VsCG6mzigdgYWfb1KfcN4gy4cc=; b=ttjR5pytOoL2SDPekKvVFkEC54801D3vQZygaG9GZ4AByIXd/gXi3gg9VomqkDtI/WEy0C 92nKPpYZm6gHjH9Nouc4VoutDaZxHKWWuwI0r2AdtWDgm986W2vkRdIb3SXlnt3k6iG4/N Uz2fWB1hmSY4uZCpJywIkBzJJYLBbFC8LzxJmptczrPx8ViI3HxY5RsnGdJAMdzSMwHzY9 kZ0rz/eojx8+fc/bSx1owUr7b1dQBObGBGizf3Vhs03x+ClrPPhGQqCzy65Y7nrISvwh2Y 65ICt0WF7L8j9j+rvSg07oyfsjoJnnYS40uBUW6lrUssYA6AzHFUKphLBqzfOg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667508932; a=rsa-sha256; cv=none; b=P4QZx7MzQYopqYZIzUOyjXSQe0qJBjNAJKJiMHrGtoBBwBW/DgEIbqeEoqFd7OO8A7xLHj gt2RZFtygP213SBw8koMJ95iyJ9vMuA7FDZNhMQRvR5auMB/L5SW1I4g9ITBuP+8lMTd6u GFuGx0o6pJPA3XzBoWRolv8uPwUxlvg1Ozq2ci4toG9F/ilee6wYCzJdfwiYjS9PUDtPsd z7Co7fRWFn2AfWQqxkYRskcf+1PGVP/iVKBSQVUdbh0RDWZMD2fi/g354puxFoz/PEqNnT Kbr0DFr5Dj+R3a8sDRo5rE+Oxu9Z3kU/QOE1vc38Xz0BI4Pt4EOkb/DVIYAaTA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=me.com header.s=1a1hai header.b=EYqBs+Pe; dmarc=pass (policy=quarantine) header.from=me.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -7.69 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=me.com header.s=1a1hai header.b=EYqBs+Pe; dmarc=pass (policy=quarantine) header.from=me.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 550D529116 X-Spam-Score: -7.69 X-Migadu-Scanner: scn0.migadu.com X-TUID: okkUTwvX1Rok Juan Manuel Mac=C3=ADas writes: Hello Juan! > I can duplicate the text, but it seems to be a bit redundant, right? > So what is the best way to proceed when doing literate programming > with any language that supports docstrings? Apologies in advance if > the question is a bit silly, but I'm not a professional programmer and > don't have an academic background in it, so I don't know if there is > any good practice on these things :-) A "bit silly" question? I find your question rather profound. Thank you for bringing it up! Personally, I recommend to use both docstrings and literate programming idiomatically, not mixing them. Literate programming exposes thinking and exploration. For example, the literate portion can show different approaches you tried but abandoned, something that does not belong to the function itself, nor in its docstring. Or, it can include examples, piece-wise performance analysis, computer science background, mathematical model, citations of prior work, and so on. Add some assertions and you will have literate tests as well. A docstring describes the function from the outside, as a black box, and if you did a good job with it, it makes it simpler for the consumer to use your function. Literate programming, on the other hand, goes deeper. It describes the thinking that went into the function, comfortably exposing its insides and opening the black box of its abstraction. Rudy --=20 "Strange as it may sound, the power of mathematics rests on its evasion of all unnecessary thought and on its wonderful saving of mental operations." -- Ernst Mach, 1838-1916 Rudolf Adamkovi=C4=8D [he/him] Studenohorsk=C3=A1 25 84103 Bratislava Slovakia