Thread: When to use COMMENT vs --

   I have used '-- ' to enter comments about tables or columns and am curious
about the value of storing comments in tables using the COMMENT key word.
When is the latter more appropriate than the former?

TIA,

Rich

On Wed, Dec 07, 2016 at 07:57:54AM -0800, Rich Shepard wrote:

>   I have used '-- ' to enter comments about tables or columns and am curious
> about the value of storing comments in tables using the COMMENT key word.
> When is the latter more appropriate than the former?

"--" only means "comment" to SQL code (such as in scripts).
PostgreSQL itself simply ignores it.

OTOH, using "comment on ... is ..." tells PostgreSQL to
_store_ a comment on a database object for later retrieval.

Karsten
--
GPG key ID E4071346 @ eu.pool.sks-keyservers.net
E167 67FD A291 2BEA 73BD  4537 78B9 A9F9 E407 1346

On Dec 7, 2016 5:07 PM, "Karsten Hilbert" <Karsten.Hilbert@gmx.net> wrote:
>
> On Wed, Dec 07, 2016 at 07:57:54AM -0800, Rich Shepard wrote:
>
> >   I have used '-- ' to enter comments about tables or columns and am curious
> > about the value of storing comments in tables using the COMMENT key word.
> > When is the latter more appropriate than the former?
>
> "--" only means "comment" to SQL code (such as in scripts).
> PostgreSQL itself simply ignores it.
>
> OTOH, using "comment on ... is ..." tells PostgreSQL to
> _store_ a comment on a database object for later retrieval.
>

This also means that tools like pg_autodoc can include it as part of the generated documentation.
> Karsten
> --
> GPG key ID E4071346 @ eu.pool.sks-keyservers.net
> E167 67FD A291 2BEA 73BD  4537 78B9 A9F9 E407 1346
>
>
> --
> Sent via pgsql-general mailing list (pgsql-general@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-general

Hi Rich

> -----Original Message-----
> From: pgsql-general-owner@postgresql.org [mailto:pgsql-general-owner@postgresql.org] On Behalf Of Chris Travers
> Sent: Mittwoch, 7. Dezember 2016 17:12
> To: Postgres General <pgsql-general@postgresql.org>
> Subject: Re: [GENERAL] When to use COMMENT vs --
>
> On Dec 7, 2016 5:07 PM, "Karsten Hilbert" <Karsten.Hilbert@gmx.net <mailto:Karsten.Hilbert@gmx.net> > wrote:
> >
> > On Wed, Dec 07, 2016 at 07:57:54AM -0800, Rich Shepard wrote:
> >
> > >   I have used '-- ' to enter comments about tables or columns and am
> > > curious about the value of storing comments in tables using the COMMENT key word.
> > > When is the latter more appropriate than the former?
> >
> > "--" only means "comment" to SQL code (such as in scripts).
> > PostgreSQL itself simply ignores it.
> >
> > OTOH, using "comment on ... is ..." tells PostgreSQL to _store_ a
> > comment on a database object for later retrieval.
> >
>
> This also means that tools like pg_autodoc can include it as part of the generated documentation.

All of the relevant differences have been mentioned by previous posters. IMHO the fact mentioned by Chris Travers that
commentson objects included in the database can be used by tools to generate the documentation is probably the most
important(besides their being persisted). As a matter of fact we have integrated this feature to extract comments to
generatethe DB documentation in our internal MediaWiki based wiki. 

If you are interested in more details on that, including additional reasons why it is a good idea to use "comments on"
insteadof comments in the source code, you may have a look at this presentation: 


http://www.schmiedewerkstatt.ch/documents/04-publications/integrating_postgresql_documentation_in_3rd_party_applications_handout_pdfa.pdf

Bye
Charles

> > Karsten
> > --
> > GPG key ID E4071346 @ eu.pool.sks-keyservers.net
> > <http://eu.pool.sks-keyservers.net>
> > E167 67FD A291 2BEA 73BD  4537 78B9 A9F9 E407 1346
> >
> >
> > --
> > Sent via pgsql-general mailing list (pgsql-general@postgresql.org
> > <mailto:pgsql-general@postgresql.org> ) To make changes to your subscription:
> > http://www.postgresql.org/mailpref/pgsql-general
>

On Thu, 8 Dec 2016, Charles Clavadetscher wrote:

> IMHO the fact mentioned by Chris Travers that comments on objects included
> in the database can be used by tools to generate the documentation is
> probably the most important (besides their being persisted).

Charles,

   Chris' contribution was the only one to answer my question.

> As a matter of fact we have integrated this feature to extract comments to
> generate the DB documentation in our internal MediaWiki based wiki.

   I'm not sure this is applicable to me. One project is for my business use,
the other for clients who will see only the entire application.

Thanks for explaining,

Rich

On Wed, Dec 7, 2016 at 9:57 AM, Rich Shepard <rshepard@appl-ecosys.com> wrote:
>   I have used '-- ' to enter comments about tables or columns and am curious
> about the value of storing comments in tables using the COMMENT key word.
> When is the latter more appropriate than the former?

Main advantage of COMMENT is that the comments are transferred to the
database such that the comments will be made available to client tools
(like psql) and external programs.  For example, if you are generating
database diagrams out of the database automatically (which is a good
idea) with a good tool (I recommend SchemaSpy) the comments will
become visible.

Code style comments OTOH will decorate the file.  This is good if you
maintain your code as proper code, checking it into git and such,
which is also a very good idea.

Personally I tend to avoid COMMENT on aesthetics; I just dislike the
COMMENT section to *after* the object being created in code. If I had
a hypothetical "COMMENT ON NEXT OBJECT 'This is ...';" I would
probably use COMMENT a lot more :-).

merlin